Security¶

ExtraSuite is designed to make automated agents useful without removing control from employees. This document explains the security model from both employee and administrator perspectives.

The Core Principle¶

If you don't share a document with your agent, the agent cannot access it. Period.

What This Means for You¶

Each employee is assigned a dedicated virtual agent with its own email address. If you share a Google Doc or Google Sheet with your agent's email address, the agent can access only that document, and only with the permission level you choose (view, comment, or edit).

You Stay in Control¶

Security Model (Technical Details)¶

Identity and Access Control¶

One service account per employee:

• Each service account represents exactly one employee's agent
• Service accounts have no default permissions
• Access exists only when an employee explicitly shares a document

Explicit, user-controlled authorization:

• Employees control access using standard Google Drive sharing
• Read, comment, and edit permissions are defined by the employee
• Access can be revoked immediately via Google Drive

No inherited or transitive access:

• Agent access is not inherited from document collaborators
• If an employee does not explicitly share a document, the agent cannot access it

Email domain allowlist:

• Organizations can restrict authentication to specific email domains
• Users outside allowed domains cannot authenticate
• Prevents unauthorized users from creating service accounts

Token and Credential Handling¶

Short-lived credentials only:

• Agents receive OAuth access tokens that expire after 1 hour
• Tokens cannot be refreshed by the agent
• Must be reissued by the server

No private key material:

• ExtraSuite does not use downloaded service account key files
• No private keys or long-lived credentials are exposed to agents or clients

Scoped Workspace access:

Issued tokens are scoped only to required Google Workspace APIs:

ExtraSuite does not issue broad Google Cloud API permissions.

Domain-Wide Delegation (Optional)¶

ExtraSuite optionally supports domain-wide delegation for user-specific APIs like Gmail, Calendar, and Apps Script. This is an opt-in feature controlled by the DELEGATION_ENABLED environment variable.

How it works:

• The server impersonates the user via Google's domain-wide delegation mechanism
• Two layers of scope enforcement:
  1. Server-side allowlist (DELEGATION_SCOPES) — optional, rejects disallowed scopes before any Google API call
  2. Google Workspace Admin Console — authoritative enforcement; if a scope isn't authorized there, the delegation call fails and the server returns 403
• All delegation requests are logged with user email, requested scopes, reason, and timestamp

Security model comparison:

Risk analysis:

• Server compromise could allow impersonation of any user for delegated scopes
• Mitigations: Cloud Run (no SSH, immutable containers), IAM audit logs, no SA key files
• Scopes are enforced at two levels: server-side DELEGATION_SCOPES allowlist and Google Workspace Admin Console

CLI Authentication Flow¶

Auth code exchange pattern:

• Tokens are never exposed in browser URLs or history
• Server generates a temporary auth code (valid for 2 minutes)
• CLI exchanges the auth code for the token via POST request
• Auth codes are single-use and deleted immediately

Localhost binding:

• The CLI callback server binds to 127.0.0.1 (not localhost)
• Prevents DNS rebinding attacks
• Only the local machine can receive the auth code

Secure token storage:

• Cached tokens are stored with restrictive file permissions
• Directory: owner read/write/execute only (0700)
• Token file: owner read/write only (0600)

Server-Side Data¶

Minimal data retention:

• The server stores only the email-to-service-account mapping
• No OAuth access tokens are stored server-side
• Session cookies are signed and stateless

Automatic expiration:

Configurable Security Settings¶

The following security settings can be configured via environment variables:

Session Cookie Settings¶

Token Settings¶

Server URL Settings¶

Security Constants¶

Auditability and Transparency¶

Clear Edit Attribution¶

All edits appear in Google Docs and Sheets version history under the agent's service account identity. There is no shared or ambiguous editor identity.

Native Rollback¶

Employees can inspect changes and revert them using Google's built-in version history. ExtraSuite does not replace or override Google Workspace revision controls.

Server-Side Logging¶

• Token generation events are logged with user email and service account
• Authentication failures are logged for security monitoring
• All logs are available through Google Cloud Logging

Limitations and Non-Goals¶

Agent Behavior is Out of Scope¶

Once a document is shared, what the agent does with that access (logic, prompts, models, workflows) is outside the scope of this security model. ExtraSuite ensures who can access what, not how an agent decides to modify content.

No Prevention of Intentional Misuse¶

If an employee grants edit access, the agent can edit within that permission. ExtraSuite does not attempt to restrict legitimate user-directed actions.

Service Account Lifecycle¶

• ExtraSuite relies on one service account per employee
• Organizations are responsible for appropriate lifecycle management
• Including offboarding and cleanup of inactive agents

Security Guarantees¶

ExtraSuite guarantees the following:

• ✅ Agents cannot access documents unless an employee explicitly shares them
• ✅ Access is limited to the permission level chosen by the employee
• ✅ All agent edits are attributable, auditable, and reversible using native Google Workspace tools
• ✅ No long-lived credentials are exposed to agents or clients
• ✅ Tokens are never exposed in browser URLs or history
• ✅ Delegated scopes (if enabled) are allowlisted by the admin
• ✅ All delegation requests are logged with user, scopes, and reason

Summary¶

ExtraSuite's security model is intentionally simple and transparent:

This design prioritizes least privilege, auditability, and employee trust while staying fully within Google Workspace's native security model.

Related:

• FAQ