Gmail Integration¶

The Gmail integration enables WhiteLotusAI to retrieve, search, and analyze email data through conversational requests. The inspected implementation also contains email-writing and mailbox-modification capabilities, which must be restricted before the integration can be approved for strict read-only operation.

Documentation status: Source-reviewed. End-to-end behavior, authorization boundaries, and read-only enforcement remain to be verified.

1. Architecture and components¶

The Gmail integration spans the chat plugin, integration-service handlers, and Gmail client. The chat plugin interprets conversational requests and dispatches operations to the integration service, where credentials and Gmail API requests are handled.

flowchart TD
    U["User request"] --> P["Email chat plugin"]
    P --> R["Conversational response"]

    P --> Q["Intent and query processing"]
    Q --> T["Tool selection and dispatch"]
    T -->|HTTP request| I["Integration service"]

    I --> A["User-specific connection and token resolution"]
    A --> C["Gmail client"]
    C --> G["Google Gmail API"]
    G --> C
    C --> I
    I --> P

    A -.-> S["OAuth and token storage"]
    S -.-> C

    classDef app fill:#e8eaf6,stroke:#5c6bc0,color:#202124
    classDef service fill:#e0f2f1,stroke:#00897b,color:#202124
    classDef external fill:#fff3e0,stroke:#ef8c00,color:#202124

    class P,Q,T,R app
    class I,A,C,S service
    class G external

The diagram represents the documented logical flow, not proof that every path is registered or reachable in the deployed application.

The chat plugin constructs requests using INTEGRATIONS_SERVICE_URL and the /api/integrations-svc base path.

2. Supported capabilities¶

2.1 Read operations¶

The chat plugin defines the following read-oriented tools:

The plugin includes parsing for sender and recipient filters, subjects, dates, categories, attachments, message states, and native Gmail search operators.

Actual results depend on query interpretation, Gmail API behavior, granted permissions, and the connected account.

2.2 Write and mailbox-modification operations¶

The source also defines operations that can change mailbox state or send messages.

The plugin metadata marks sending, drafting, replying, and forwarding as confirmation-requiring operations. Trash is categorized as destructive and requires confirmation. Some other modification tools do not declare confirmation requirements in their definitions.

Required policy: Disable or block every write-capable operation across tool registration, tool dispatch, and integration API routes. Verify the actual enforcement with negative tests before declaring compliance.

3. OAuth authentication¶

3.1 Authorization flow¶

The primary Gmail OAuth implementation is located in integrations/package/app/handlers/integration_handlers.py.

sequenceDiagram
    autonumber
    participant F as Frontend
    participant I as Integration service
    participant R as Redis
    participant G as Google OAuth
    participant U as User service

    F->>I: Start authorization with application JWT
    I->>I: Decode JWT and identify user
    I->>I: Generate state and PKCE verifier/challenge
    I->>R: Store state and verifier with TTL
    I-->>F: Redirect to Google authorization
    F->>G: Authorize requested scopes
    G-->>I: Callback with code and state
    I->>R: Retrieve and consume stored state
    I->>G: Exchange code using PKCE verifier
    G-->>I: OAuth tokens
    I->>I: Store token data server-side
    I->>U: Update connection status where supported
    I-->>F: Redirect with connection status

The documented implementation follows these steps:

1. The frontend initiates Gmail authorization and supplies the application JWT.
2. The integration handler decodes the JWT to identify the user.
3. The handler generates a PKCE verifier, an S256 challenge, and a random state value.
4. The verifier and user association are stored in Redis with a ten-minute expiration.
5. The browser is redirected to Google's OAuth authorization page.
6. Google returns an authorization code and state to the callback.
7. The handler retrieves and deletes the stored state entry and exchanges the code using the PKCE verifier.
8. The handler requires a refresh token and stores token data server-side.
9. The user's Gmail connection is marked active where the connection update succeeds.
10. The browser is redirected to the frontend with a connection-status indicator.

The success redirect is not intended to include token values. Verify this behavior for error redirects and every registered OAuth callback as well.

3.2 Requested OAuth scopes¶

The primary implementation requests all five scopes. The compose and modify scopes are broader than a strict read-only integration requires.

3.3 User-specific token resolution¶

The inspected integration handler:

• Checks the user's Gmail connection status.
• Retrieves stored token data for the requesting user.
• Returns token information for downstream Gmail API calls.
• Returns an unavailable-token result when the connection is inactive or token lookup fails.

The Gmail client can reuse a valid access token and request a replacement from Google's OAuth token endpoint when necessary. It also attempts to persist refreshed token data through the user service.

A global GMAIL_REFRESH_TOKEN fallback exists in some code paths. Until its use is verified and appropriately restricted, strict per-user isolation must not be assumed.

4. API reference¶

The routes below are documented from integrations/package/app/handlers/integration_handlers.py. Their effective prefix is /api/integrations-svc.

Routing caveat: The separate gmail_handlers.py module contains additional handlers. Confirm router registration and effective reachability in the deployed application before treating this table as an exhaustive API inventory.

4.1 OAuth and authentication¶

4.2 Read endpoints¶

4.3 Write endpoints¶

These routes must be denied in strict read-only mode.

The existence of a route does not establish that it is appropriately authenticated, authorized, or protected by the read-only policy.

5. Configuration and credential handling¶

The following settings are referenced by the inspected implementation. Confirm their authoritative definitions, required values, and defaults against the repository's configuration and deployment files.

5.1 Security requirements¶

• Never commit OAuth client secrets, access tokens, or refresh tokens to version control.
• Keep production credentials in the approved secret-management system.
• Never publish secrets in documentation, logs, screenshots, or issue reports.
• Enforce user-specific credential lookup and authorization on every request.
• Avoid shared global refresh tokens when strict per-user isolation is required.
• Review requested OAuth scopes and remove unnecessary write permissions.
• Redact sensitive provider responses and prevent email content from leaking into logs.
• Restrict internal-service endpoints to authenticated, authorized callers.

5.2 Example environment configuration¶

The following is a template, not a complete deployment configuration. Supply values through the approved secrets and environment-management mechanism.

GMAIL_CLIENT_ID=<google-oauth-client-id>
GMAIL_CLIENT_SECRET=<managed-secret>
GMAIL_REDIRECT_URI=<registered-callback-uri>

JWT_SECRET_KEY=<managed-application-secret>
JWT_ALGORITHM=<configured-jwt-algorithm>
INTERNAL_SECRET=<managed-internal-service-secret>

FRONTEND_URL=<frontend-base-url>
INTEGRATIONS_SERVICE_URL=<integration-service-base-url>
USER_SERVICE_URL=<user-service-base-url>

Do not place actual credentials in the documentation. The global refresh-token fallback and sender-address settings are intentionally omitted from this baseline template because their necessity and intended production use must first be verified.

6. Query processing and result handling¶

The email plugin translates conversational requests into Gmail search queries instead of passing every natural-language request directly to the provider.

The plugin also preserves message and thread references in response-processing logic so later conversational requests can refer to previously retrieved emails.

These are documented implementation capabilities, not a guarantee that every natural-language request will be interpreted correctly. Regression tests should cover ambiguous phrasing, empty results, date boundaries, and provider-specific query behavior.

7. Error handling and observability¶

The inspected implementation uses HTTP status checks, exceptions, and logging around Gmail API requests and OAuth processing. The chat plugin also handles integration-service errors and includes a health-check method that requests a small inbox result.

Logging requirements: Do not expose access tokens, refresh tokens, authorization codes, message bodies, or unnecessary provider response details. Review existing logging paths before production use.

A successful HTTP response or a health endpoint response alone does not establish full integration readiness.

8. Security findings and remediation priorities¶

The following findings are based on source inspection. They are not claims that fixes have been implemented or that tests have passed.

Priorities indicate suggested remediation order, not a completed security assessment or a formal risk acceptance.

9. Verification checklist¶

Use this checklist during implementation review and release validation. Mark items complete only when supported by test evidence.

OAuth and credential security¶

• OAuth consent and callback work with a dedicated test account.
• PKCE state expires and can be consumed only once.
• Invalid, missing, expired, and replayed state values fail safely.
• Credentials remain server-side and never appear in frontend responses.
• User A cannot retrieve User B's messages, tokens, or connection data.
• Missing connections and invalid internal-service credentials fail closed.
• Token refresh, persistence failures, and concurrent refreshes are tested.
• OAuth redirects and logs do not expose secrets or authorization codes.

Read-only enforcement¶

• Every write-capable tool is disabled or rejected.
• Direct requests to every write endpoint are denied.
• Read-only enforcement cannot be bypassed by supplying confirmation metadata.
• No alternate or duplicate route bypasses the policy.
• OAuth scopes match the approved read-only behavior.
• Negative tests confirm that no mailbox state or message is changed.

Functional and operational validation¶

• Inbox, search, message, thread, and label retrieval return expected results.
• Attachment listing and downloads enforce user authorization.
• Result limits, identifiers, and query parameters are validated.
• Natural-language search regression tests cover dates, senders, phrases, attachments, ambiguity, and empty results.
• Error responses and logs do not expose secrets or unnecessary message content.
• Health checks reflect the readiness criteria adopted for deployment.
• End-to-end tests pass against the intended deployment configuration.

10. Source of truth and change management¶

The source repository remains authoritative for implementation behavior. Review this page whenever the Gmail plugin, OAuth scopes, token storage, integration routes, configuration, or read-only policy changes.

Keep the following distinctions explicit during future updates:

• Implemented: Supported by source inspection.
• Verified: Confirmed by reproducible tests or deployment evidence.
• Required: A security, operational, or product acceptance criterion that may not yet be implemented.

Do not document a capability as a security guarantee until its enforcement has been verified and tested.