Google Services Secure

Secure Google Workspace integration (Gmail, Drive, Calendar, Sheets, Docs, Contacts, etc.) with enterprise-grade security. Features credential isolation, inp...

Security Scan

The skill claims enterprise-grade, RAM-only credential handling, but its included scripts persist OAuth tokens and modify local files (token file + audit logs) and the declared metadata/env requirements are inconsistent — review and fix before use.

Purpose & Capability

Name/description match the included functionality (Google Workspace OAuth integration). Requested environment variables for Google credentials are appropriate for this purpose. However the registry's declared required env list omits GOOGLE_REDIRECT_URI while SKILL.md and scripts rely on it — a metadata/instruction mismatch that should be corrected.

Instruction Scope

SKILL.md instructs running the included scripts (./scripts/validate-setup.sh and ./scripts/auth-google.sh). Those scripts create/modify local files (/data/.openclaw/logs/google-services-audit.log, $HOME/.google-oauth-token), validate configs, and call external Google endpoints. The documentation repeatedly asserts tokens are 'RAM only', but auth-google.sh writes the token response to $HOME/.google-oauth-token and validate-setup.sh checks/creates audit files — this contradicts the 'never stored in files' claim and expands scope beyond purely transient in-memory handling.

Install Mechanism

No external install or remote downloads; this is an instruction + script bundle. There is no high-risk remote fetch or installer. Scripts are local and will be executed by the user/agent when invoked.

Credentials

Requested environment variables (GOOGLE_API_KEY, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET) are appropriate for Google API integration, but SKILL.md and scripts also require GOOGLE_REDIRECT_URI (present in some files/_meta.json but missing from the registry's required list). The scripts also instruct setting other optional envs (GOOGLE_PERMISSION_MODE, rate limits). The main proportionality concern is unjustified secrecy claims: the skill claims tokens won't be written to disk yet the auth script writes tokens to a file and stores audit logs — requiring sensitive secrets while simultaneously persisting tokens increases exposure risk.

Persistence & Privilege

always:false (normal). The skill's scripts create persistent artifacts (token file at $HOME/.google-oauth-token and audit log under /data/.openclaw/logs). Creating/reading these files is expected for a credential management script, but it conflicts with the documentation's promise of RAM-only token storage and therefore raises a persistence/privacy concern.

What to consider before installing

This skill is coherent in purpose (Google OAuth integration) but contains important contradictions and persistence behavior you should not ignore: - The documentation repeatedly claims OAuth tokens are stored only in memory, but scripts (scripts/auth-google.sh) write the token response to $HOME/.google-oauth-token and set file permissions. That means tokens can persist on disk and be read by processes/users with access to that path. Treat this as a real exposure risk until the behavior is fixed. - The registry metadata omits GOOGLE_REDIRECT_URI even though SKILL.md and the scripts depend on it. Ask the author to update required envs and documentation to match the actual runtime requirements. - If you consider using this skill: inspect and (if needed) modify auth-google.sh to avoid writing tokens to disk (or change TOKEN_FILE to a secure ephemeral store you control), ensure audit logs are stored in a location you trust, and verify permissions. Alternatively run the skill in an isolated sandboxed account or VM and rotate/revoke tokens after testing. - Ask the maintainer for clarification and a corrected release that either: (a) truly keeps tokens RAM-only, or (b) documents and allows a configurable secure token storage path (with clear warnings). - Until resolved, avoid placing high-privilege Google credentials in shared systems; consider creating a minimally scoped test account for evaluation and revoke credentials after use.

🔒 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:

# 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:

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

3. OAuth 2.0 Flow:

# Generate OAuth URL and authenticate
./scripts/auth-google.sh

Quick Start

1. Configure Environment Variables

# 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

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

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)

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:

{
  "env": {
    "GOOGLE_API_KEY": "AIza...",  // ❌ INSECURE
    "GOOGLE_CLIENT_ID": "...apps.googleusercontent.com",  // ❌ INSECURE
    "GOOGLE_CLIENT_SECRET": "..."  // ❌ CRITICAL SECURITY ISSUE
  }
}

✅ CORRECT approach:

# 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

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

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:

export GOOGLE_PERMISSION_MODE="readonly"  # Recommended for production

Audit Logging

All actions are logged to:

/data/.openclaw/logs/google-services-audit.log

Log format:

{
  "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:

export GOOGLE_RATE_LIMIT_GMAIL="100/minute"
export GOOGLE_RATE_LIMIT_DRIVE="500/minute"

Available Services

📧 Gmail (gmail.googleapis.com)

1. List Messages

curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

2. Get Message

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

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: [e-mail]\r\nTo: [e-mail]\r\nSubject: Test\r\n\r\nTest message body"
  }'

💾 Google Drive (drive.googleapis.com)

1. List Files

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

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

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

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

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

curl -s "https://sheets.googleapis.com/v4/spreadsheets" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

2. Read Sheet Values

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

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

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

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

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

curl -X POST "https://people.googleapis.com/v1/people:createContact" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddresses": [{"value": "[e-mail]"}],
    "names": [{"givenName": "John", "familyName": "Doe"}]
  }'

Input Validation

Email Validation

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

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

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

#!/bin/bash
# Send automated email notifications
EMAIL_SUBJECT="Daily Report"
RECIPIENT="[e-mail]"
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: [e-mail]\\r\\nTo: $RECIPIENT\\r\\nSubject: $EMAIL_SUBJECT\\r\\n\\r\\n$MESSAGE_BODY\"
  }"

Use Case 2: File Backup

#!/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

#!/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

# 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

# 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

{
  "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

# 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.