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¶

Typed command protocol:

Every token request uses a typed command — a structured object declaring the exact operation the agent intends to perform (e.g. sheet.pull, gmail.compose, calendar.view). The server uses the command type to determine what credential to issue. No credential is issued speculatively or in bulk.

Two credential types, minimum scope:

• Service account tokens give the agent access only to files explicitly shared with its service account
• Delegated tokens impersonate the user for a single scope; the scope allowlist is controlled by the administrator

Short-lived Google access tokens:

• Google access tokens expire after 1 hour (configurable)
• Tokens are generated on demand and never stored server-side or client-side; the client holds them only in process memory
• The agent cannot refresh a token — it must request a new one via the server

Session token (stored in OS keyring):

• After the initial browser-based login, the client stores a session token in the OS keyring (macOS Keychain, Linux SecretService, Windows Credential Locker)
• The only file written to disk is ~/.config/extrasuite/profiles.json (0600), which contains profile names and email addresses — no tokens
• The session token authenticates the client to the ExtraSuite server only — it is never sent to Google APIs
• Session tokens are stored as SHA-256 hashes in Firestore; the raw token never touches the database
• Sessions can be listed and revoked at any time via extrasuite auth logout

No private key material:

• ExtraSuite does not use downloaded service account key files
• No Google private keys or refresh tokens are exposed to agents or clients

Agent intent logging:

Every token request includes a reason field — the agent's stated purpose for the operation. The server logs the user email, command type, command context, and reason to an audit log before issuing any token. This creates a record of not just what was accessed, but why the agent claimed it was needed.

Administrators can also configure a DELEGATION_SCOPES allowlist. Token requests for scopes outside this list are rejected before any Google API call is made.

Domain-Wide Delegation (Optional)¶

ExtraSuite supports domain-wide delegation for user-specific APIs like Gmail, Calendar, Apps Script, and Contacts when those command types are enabled by your deployment and authorized in Google Workspace.

How it works:

• The server impersonates the user via Google's domain-wide delegation mechanism
• The client sends a typed command object (e.g. {"type": "gmail.compose", "to": ["..."], ...}) and a reason string; the server's command registry maps the command type to the required OAuth scope(s)
• The server validates the command type and looks up the exact scope(s) needed — the client never specifies scopes directly
• 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, command type, full command context, reason, and timestamp before any token is issued

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¶

Phase 1 — Initial login (once per 30 days, browser required):

1. extrasuite auth login opens a browser for Google OAuth
2. The server generates a temporary auth code (valid 2 minutes)
3. The CLI exchanges the auth code for a session token via POST request
4. Auth codes are single-use and deleted immediately after exchange
5. The session token is stored locally and used to authenticate all subsequent requests

Phase 2 — Per-command token exchange (headless, no browser):

1. The CLI sends a typed command + reason to POST /api/auth/token, authenticated with the session token in the Authorization header (never in the URL or body)
2. The server validates the session token (hash lookup in Firestore), then routes based on command type to issue the appropriate Google access token
3. The CLI uses the returned token for the Google API call and discards it when done

Localhost binding:

• The OAuth 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:

• Session tokens are stored in the OS keyring (macOS Keychain, Linux SecretService, Windows Credential Locker) — nothing sensitive on disk
• The only on-disk file is ~/.config/extrasuite/profiles.json (0600), containing profile names and email addresses only
• Access tokens are never written to disk; they are held in process memory for the duration of the command

Server-Side Data¶

Minimal data retention:

• The server stores the email-to-service-account mapping and session token hashes
• Session tokens are stored as SHA-256 hashes in Firestore (the raw token never touches the database)
• No Google OAuth access tokens are stored server-side — they are generated on demand and returned directly to the client
• Access logs store command type, command context (non-sensitive fields like file URLs), and the agent's stated reason — not file contents or sensitive data

Automatic expiration:

Configurable Security Settings¶

The following security settings can be configured via environment variables:

Session Token Settings¶

Access 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
• ✅ Google access tokens are short-lived (1 hour), generated on demand, held only in process memory, and never stored client-side or server-side
• ✅ The local session token (30 days) only authenticates against the ExtraSuite server — it has no Google API access on its own
• ✅ Google access tokens are never exposed in browser URLs or history
• ✅ Every token request is logged with the command type, context, and the agent's stated reason before any token is issued
• ✅ Delegated scopes (if enabled) are allowlisted by the admin at two levels: server config and Google Workspace Admin Console
• ✅ The client declares the intended operation via a typed command; the server determines the scope — agents cannot request arbitrary scopes

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