Google Drive Integration¶

The Google Drive integration enables WhiteLotusAI to discover files, search indexed content, retrieve file metadata, and inspect sharing information through the authenticated user's Google Drive connection.

1. Purpose and capabilities¶

The integration allows users to locate and inspect files available to their connected Google account.

The intended initial release is read-only. It must not create, edit, move, copy, rename, trash, star, or share files, or change file permissions.

1.1 Capability overview¶

The current implementation primarily retrieves file listings and metadata. Searching fullText can find content indexed by Google Drive, but it does not establish that WhiteLotusAI downloads or returns the complete contents of a document.

2. Registered tools¶

The chat-side plugin is implemented in:

chat/package/app/plugins/google_drive/plugin.py

2.1 Read operations¶

The following tools are categorized as READ in the chat plugin.

Categorization is not a substitute for authentication or authorization. Each request must verify the user's connection and enforce access to the requested resource.

2.2 Write operations that must be blocked¶

The following registered operations are incompatible with the initial read-only release.

These tools are categorized as WRITE. Some request confirmation, but confirmation alone does not enforce a read-only policy. In particular, star_file does not require confirmation in its tool definition.

3. Architecture and request flow¶

3.1 Components¶

3.2 Read request lifecycle¶

flowchart TD
    U["Authenticated user"] --> C["Chat service"]
    C --> R{"Approved read tool?"}
    R -- "No" --> D["Reject operation"]
    R -- "Yes" --> P["Plugin calls integrations service"]
    P --> A["Validate internal caller and user identity"]
    A --> K{"Drive connected and authorized?"}
    K -- "No" --> X["Return controlled error"]
    K -- "Yes" --> T["Resolve user's credentials"]
    T --> G["Google Drive API v3"]
    G --> F["Format metadata or search results"]
    F --> O["Return response to chat"]

    classDef entry fill:#e8f0fe,stroke:#4285f4,color:#172b4d
    classDef process fill:#e8f5e9,stroke:#388e3c,color:#173b25
    classDef decision fill:#fff3cd,stroke:#b8860b,color:#493800
    classDef blocked fill:#fce8e6,stroke:#c5221f,color:#5f1717
    class U,C entry
    class P,A,T,G,F,O process
    class R,K decision
    class D,X blocked

The diagram describes the intended read path. It is not evidence that every boundary has passed end-to-end security testing.

3.3 Internal service boundary¶

When a user ID is available, the chat plugin sends the following headers to the integrations service:

• X-User-Id
• X-Internal-Secret

The integrations handler checks the internal secret and verifies the user's Google Drive connection before resolving the user's token.

Security requirements:

• Internal routes must be accessible only through the intended authenticated service boundary.
• An external client must not be able to impersonate a user by supplying X-User-Id.
• Internal authentication must be independently validated; the presence of a header is not proof of trust.
• The user identity used for token resolution must be tied to a trusted authenticated request.
• Write-capable routes must remain protected even if callers bypass the chat plugin.

4. OAuth and configuration¶

4.1 Configuration variables¶

The current Google Drive OAuth handler references the following configuration variables.

The plugin's env_vars declaration also lists GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET. This reflects the current implementation's naming; it is not a recommendation to reuse credentials indiscriminately across applications or environments.

Before enabling the integration, verify the actual deployment configuration, Google Cloud OAuth client registration, callback URI, and connection-status checks.

4.2 OAuth scopes¶

The current OAuth handler requests these scopes:

The drive.readonly and drive.metadata.readonly scopes support read access. The additional drive.file scope is broader than a strict metadata-only requirement and must be assessed against the intended functionality.

4.3 OAuth authorization flow¶

The current handler implements the following flow:

1. The OAuth-start endpoint receives an application token.
2. The handler validates the token and extracts the user ID.
3. A PKCE verifier and challenge are generated.
4. A random state value is stored with the verifier and user ID.
5. The browser is redirected to Google's authorization endpoint.
6. The callback retrieves the stored state data and exchanges the authorization code.
7. The handler stores the access token, refresh token, expiry, and scope information for the user.
8. The user's Google Drive connection is marked active.
9. The browser is redirected to the frontend with a connection result.

The existence of these steps in the source does not establish that every failure case is handled securely.

4.4 OAuth validation checklist¶

Verify the following before enabling the integration:

• State values are unpredictable, validated, and protected against replay.
• PKCE verification is enforced during authorization-code exchange.
• Invalid or expired application tokens are rejected.
• Callback errors do not expose tokens or sensitive details.
• Tokens are stored securely and associated with the correct user.
• Refresh-token rotation and expiry updates are handled correctly.
• Revoked or insufficient-scope credentials fail safely.
• Disconnecting Drive prevents subsequent access.
• Redirect destinations are restricted to approved frontend URLs.

5. Search and metadata behavior¶

5.1 File listing¶

The listing endpoint calls the Google Drive API v3 files resource and requests fields that include:

• File ID and name
• MIME type
• Modification time
• File size
• Web-view link
• Owner information

The integrations handler defaults to 20 results, while the chat plugin commonly requests 10.

These are defaults, not necessarily maximums. Validate and enforce a server-side upper limit on incoming max_results values. Verify pagination behavior and ensure that response sizes remain bounded.

5.2 Search behavior¶

The search endpoint builds a Google Drive query using name contains and fullText contains, then orders results by modification time.

The plugin also supports searches by:

• MIME type
• Modification date
• Shared status
• Starred status

Search inputs must be validated and safely encoded. The current query construction inserts search text into a Drive query string, so test apostrophes, special characters, and malformed input to ensure that the query remains correctly structured.

5.3 File types and content limitations¶

The plugin formats metadata and links for supported file types, including:

The table describes metadata and link formatting, not complete file-content extraction.

Do not claim that the integration can download document bodies, extract PDF text, interpret images, or analyze file contents unless the corresponding functionality is implemented and tested separately.

6. Read-only enforcement¶

A strict read-only release requires enforcement at multiple layers. No single control should be treated as sufficient.

6.1 Required controls¶

6.2 Enforcement requirements¶

• Allow only the approved read tools in the chat execution path.
• Block every registered write tool before its implementation runs.
• Review integrations service routes independently of the chat registry.
• Prevent direct access to write-capable routes by unauthorized callers.
• Do not rely solely on confirmation prompts, intent-routing rules, or assistant instructions.
• Verify that denied operations never reach a mutating Google API endpoint.
• Confirm that denied requests leave files, folder structures, stars, and sharing permissions unchanged.

The integrations service exposes write-capable endpoints for file creation, file updates, copying, moving, and permission creation or deletion. These routes must be restricted to the intended internal callers. Hiding write tools in the chat interface does not secure those endpoints.

7. Security and privacy¶

Google Drive files may contain confidential business information, personal data, financial records, and text designed to manipulate an AI assistant.

7.1 Security requirements¶

• Identity: Resolve credentials for the authenticated user.
• Connection checks: Validate the user's Drive connection before every request.
• Authorization: Respect Google-side permissions and application-level access controls.
• Least privilege: Request only the OAuth scopes required by approved functionality.
• Input validation: Validate file IDs, search terms, dates, and result limits.
• Resource limits: Bound result counts, timeouts, pagination, and any future content-download size.
• Secret handling: Never expose access tokens, refresh tokens, authorization codes, or internal secrets in errors.
• Logging: Avoid logging full document contents or sensitive metadata by default.
• Mutation protection: Do not create, edit, move, copy, rename, trash, star, or share files in the read-only release.
• Cache isolation: If caching is introduced, isolate cached data by user and request context.

7.2 Treat retrieved content as untrusted¶

If document-content retrieval is introduced later, treat retrieved content as untrusted input. Instructions embedded in a document must not override system policy, user authorization, or tool permissions.

A file being accessible through Google Drive does not authorize the assistant to execute instructions contained within it.

8. Troubleshooting¶

Do not resolve authentication failures by placing real credentials in source files or documentation.

9. Testing checklist¶

Use a dedicated test account and non-sensitive Drive files. Validate both successful read operations and explicit denial of all prohibited mutations.

9.1 Functional tests¶

• List recent files.
• Search by file name and indexed full text.
• Retrieve metadata for an accessible file.
• Search by file type and modification date.
• List shared files and starred files.
• List folders and inspect file permissions.
• Handle empty results and inaccessible file IDs.
• Test apostrophes and special characters in search terms.
• Validate result limits and pagination.
• Handle expired tokens, revoked access, timeouts, and API rate limits.

9.2 Authorization and read-only tests¶

• An unconnected user cannot access Drive.
• One user cannot access another user's credentials or Drive data.
• Only approved read operations are callable in the initial release.
• Every registered write tool is rejected in read-only mode.
• Direct calls to write-capable integrations routes are rejected for unauthorized callers.
• Denied operations do not create, move, copy, rename, star, or trash files.
• Denied operations do not create or remove sharing permissions.
• Crafted tool calls cannot bypass the read-only policy.
• Forged internal identity headers are rejected at the service boundary.
• Denied operations produce no mutation requests to Google APIs.

9.3 OAuth tests¶

• The OAuth-start endpoint rejects invalid application tokens.
• State and PKCE validation work as intended.
• Callback failures are handled without exposing secrets.
• Tokens are associated with the correct user.
• Token refresh works and updated expiry data is persisted.
• Missing, expired, revoked, and insufficient-scope credentials fail safely.
• Disconnecting Drive prevents subsequent access.

10. Source references¶

The following files are the primary implementation references for this integration.

When implementation behavior changes, update this page alongside the relevant code and tests. Recheck OAuth scopes, tool registration, and integrations service routes whenever read-only enforcement is modified.

11. Release readiness¶

The current source contains write-capable tools and service routes, and the OAuth flow requests drive.file. These are material considerations for a strictly read-only release.

Before approving production use, verify all of the following:

• Approved read operations are documented and tested.
• Write-capable tools are blocked before execution.
• Direct mutation routes are appropriately protected.
• Per-user credential and data isolation is verified.
• OAuth scopes have been reviewed and minimized.
• OAuth state, PKCE, token storage, and refresh behavior are tested.
• Search input validation and result limits are enforced.
• Denied operations have been verified to produce no side effects.
• Security and functional test results have been reviewed.

Readiness decision: Do not declare Google Drive production-ready for the read-only release until authorization enforcement, per-user credential isolation, least-privilege scopes, route protection, and negative security tests have been verified.

The presence of a registered tool or route establishes that it is represented in the code; it does not establish that the integration has passed end-to-end testing.