Google Calendar Integration¶

The Google Calendar integration connects WhiteLotusAI's conversational interface to Google Calendar through the chat plugin and integrations service. It provides event retrieval and contains implementation paths for event creation and deletion.

This document describes the implementation identified in the available source snapshot. It does not certify production availability, end-to-end correctness, or enforcement of the intended read-only security policy.

At a glance¶

1. Architecture¶

The integration has three primary implementation layers.

The integrations service registers its integration router under /api/integrations-svc. The chat plugin uses INTEGRATIONS_SERVICE_URL to construct the integration API base URL.

The effective external URL depends on gateway routing, environment configuration, and deployment.

Request flow¶

flowchart TD
    U["User request"] --> C["WhiteLotusAI chat"]
    C --> P["Google Calendar plugin"]
    P --> R["Formatted response"]
    P --> I["Integrations service"]
    O["Google OAuth and PKCE"] -.-> A
    I --> A["User identity and token resolution"]
    A --> G["Google Calendar API v3"]
    G --> I
    I --> P

    A -.-> T["Stored provider tokens"]

    classDef action fill:#E8F1FE,stroke:#356AC3,color:#172B4D,stroke-width:1.5px
    classDef security fill:#EDE9FE,stroke:#7C3AED,color:#3B0764,stroke-width:1.5px
    classDef external fill:#DDF5E5,stroke:#25804B,color:#16452B,stroke-width:1.5px
    classDef data fill:#FFF2CC,stroke:#B8860B,color:#4D3B00,stroke-width:1.5px
    classDef response fill:#D1FAE5,stroke:#047857,color:#064E3B,stroke-width:1.5px

    class U,C,P,I action
    class O security
    class A,G external
    class T data
    class R response

The diagram represents the documented logical flow. Exact runtime call ordering, network boundaries, and credential-storage behavior should be confirmed against the deployed configuration.

2. Tool definitions and supported operations¶

The inspected chat plugin declares three tools.

2.1 List events¶

The list_events tool retrieves events from the primary calendar and formats the response as a text list. Where available, the output includes the event summary and its start date or datetime.

The integration handler requests Google Calendar API v3 event data with the following behavior:

• Uses the primary calendar.
• Orders results by start time.
• Expands recurring events into individual occurrences.
• Defaults max_results to 10.
• Defaults time_min to the current UTC time when the parameter is absent.

The inspected route does not declare an upper bound for max_results.

2.2 Create an event¶

The create_event tool declares the following parameters.

The chat plugin checks that the event title, start, and end values are present. It constructs an event payload and sends it to the integrations service.

The handler forwards the JSON body to Google Calendar API v3 to create an event on the primary calendar. It accepts provider responses with status 200 or 201.

Implementation limitation: the inspected handler reads the request body as JSON rather than validating it against a dedicated event request model. Input validation, datetime semantics, attendee validation, and malformed-payload handling require separate verification.

This operation changes calendar state and is outside a strict read-only policy.

2.3 Delete an event¶

The delete_event tool accepts an event_id string.

The plugin sends a DELETE request to the integration route for that event. The handler issues a delete request against the primary Google Calendar and returns a response containing the deleted event identifier when the provider returns 200 or 204.

Deleting an event is a destructive, state-changing operation. It must not be available under a strict read-only integration policy.

3. Integration API endpoints¶

The inspected source declares the following service-level routes.

The access classifications above describe the intended purpose of each route, not a verified authorization result.

The externally reachable URLs depend on gateway proxy configuration and the deployment environment.

4. OAuth and credential management¶

4.1 Configuration variables¶

The inspected implementation references the following settings.

The chat plugin's env_vars property lists GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET. The integration handler additionally references GOOGLE_CAL_REDIRECT_URI and other application settings.

These references are not a complete deployment configuration specification. The actual values must be supplied through the deployment's approved secret-management mechanism.

4.2 Authorization flow¶

The inspected implementation follows this logical sequence.

sequenceDiagram
    actor U as User
    participant F as WhiteLotusAI Frontend
    participant I as Integrations Service
    participant G as Google OAuth
    participant S as User Service

    U->>F: Connect Google Calendar
    F->>I: OAuth start with application token
    I->>I: Decode token and obtain user ID
    I->>I: Generate PKCE verifier, challenge, and state
    I->>G: Redirect to authorization endpoint
    G-->>U: Request consent
    U->>G: Approve authorization
    G->>I: Callback with code and state
    I->>I: Validate and consume stored state
    I->>G: Exchange code using PKCE verifier
    G-->>I: Provider tokens
    I->>S: Attempt token storage
    I->>S: Attempt connection-status update
    I-->>F: Redirect with outcome

The diagram summarizes the inspected flow; it does not establish that every failure path is handled securely or that all service calls succeed.

The implementation performs the following steps:

1. Receives an application token in the OAuth start route's token query parameter.
2. Decodes the token and obtains the user identifier from the sub claim.
3. Generates a PKCE verifier and challenge.
4. Generates a random OAuth state value and stores the state, verifier, and user identifier.
5. Redirects to Google's authorization endpoint with the configured client ID, callback URI, scopes, state, and PKCE challenge.
6. Retrieves and removes the stored state entry during the callback.
7. Exchanges the authorization code using the stored PKCE verifier.
8. Requires a refresh token and attempts to store provider tokens through the user service.
9. Attempts to mark the user's Google Calendar connection as active.
10. Redirects the browser to the frontend with a success or error indicator.

The source checks for OAuth errors and rejects missing or invalid stored state. Further verification is needed for token validation, state-store behavior, callback failure handling, and safe handling of authentication errors.

4.3 Token resolution and refresh¶

The integration handler's token-resolution helper requires a user identifier and a matching INTERNAL_SECRET before resolving the user's stored Google Calendar token. It also checks whether the user has explicitly connected the integration.

The access-token helper:

• Checks whether the access token is missing or expired.
• Attempts to obtain a replacement access token when refresh is needed and a refresh token is available.
• Attempts to persist updated expiry information.
• Raises HTTP 401 when an access token remains unavailable, indicating that Google Calendar is not connected.

The following cases remain unverified:

• Refresh-token rejection or revocation by Google.
• Failure to persist refreshed tokens or expiry information.
• Unavailable user-service or token-storage dependencies.
• Inconsistent connection-status and token records.
• Concurrent refresh requests for the same user.

5. OAuth scopes and permissions¶

The inspected handler requests these Google OAuth scopes:

OAuth scopes constrain provider-authorized capabilities; they do not replace application-level authorization checks. A read-only policy should be enforced independently in the tool registry and integration service.

6. Error handling and timeouts¶

The inspected code uses the following HTTP timeouts.

The chat plugin handles several response conditions:

• HTTP 401 returns a message indicating that Google Calendar is not connected.
• Other unsuccessful event-list responses produce a status-based error message.
• Failed create or delete requests produce operation-specific messages.
• Exceptions are logged as warnings, and the plugin returns a generic temporary-unavailability message.

The integration handlers raise HTTP exceptions when Google Calendar returns unsuccessful responses. Some error paths include provider response text in the exception detail.

The presence of timeouts does not establish complete request cancellation, retry behavior, or consistent error handling across every failure path.

7. Date and time handling¶

The chat plugin's default time-range helper uses UTC.

The helper does not derive the user's local timezone from the request.

The create-event helper also appends Z to datetime strings that do not already include a timezone offset or Z, treating those values as UTC.

This behavior may produce unexpected event selection or scheduling when a user expresses times in a local timezone.

8. Caching and health reporting¶

Caching¶

The integrations handler module describes Redis-backed caching for integration results. The precise cache coverage and invalidation behavior for Google Calendar must be verified against the relevant handler and cache calls.

Review at least the following:

• Whether calendar event responses are cached.
• Whether cache keys isolate individual users and relevant query parameters.
• Whether event changes invalidate cached results.
• Whether cached data can remain accessible after a user disconnects the integration.
• Whether token or credential data is excluded from inappropriate cache entries.

These are verification questions, not confirmed cache defects.

Health reporting¶

The chat plugin's health_check method returns True and describes the integration as OAuth-only, with connection validity checked during execution.

A successful plugin health check does not establish that:

• A particular user's OAuth connection is valid.
• The stored refresh token remains usable.
• Google Calendar is reachable.
• The user has sufficient provider permissions.
• A calendar operation will succeed.

Distinguish plugin registration health from per-user connection health and provider availability in operational monitoring.

9. Security and verification findings¶

The following register records source-review findings and follow-up requirements. No application code has been modified as part of this documentation update.

Recommended verification order¶

1. Security boundary: establish that write operations are rejected throughout the application when read-only mode is required.
2. OAuth permissions: confirm the minimum scopes and validate user consent and token handling.
3. Identity isolation: verify that every request resolves credentials for the authenticated user and cannot access another user's calendar.
4. Input and resource limits: validate event-list parameters, request payloads, pagination, and datetime inputs.
5. Reliability: test token refresh, provider errors, storage outages, timeouts, and recovery behavior.
6. Observability: verify health reporting, cache invalidation, and safe logging.
7. End-to-end coverage: execute integration tests against a dedicated test calendar and document the actual results.

10. Source references¶

The following files are the primary source locations identified during this review.

11. Verification status and maintenance¶

Update this page when new source inspection, automated tests, or runtime evidence changes a finding. Record the test environment, test result, and relevant implementation revision when marking a verification item complete.

Acceptance criterion for a read-only release: event retrieval must work for the authorized user, while event creation and deletion must be rejected at the applicable enforcement boundaries. OAuth permissions must also be consistent with the approved read-only design.

Related documentation: Third-Party Integrations · Read-Only Integration Test Plan · Security Overview