Third-Party Integrations¶

This document describes the third-party integrations represented in WhiteLotusAI's source code and establishes the documentation, security, and verification requirements for enabling them.

It serves as the entry point for provider-specific documentation, integration architecture, authentication and authorization, data protection, operational reliability, and testing.

1. Integration inventory¶

WhiteLotusAI contains plugin implementations for six external services.

Understanding integration status¶

These states are independent. Documentation must report each state accurately rather than treating them as interchangeable.

2. Integration architecture¶

WhiteLotusAI separates plugin orchestration from provider-specific integration handling. The chat service registers plugins and their tools, while the integrations service contains provider-related clients, handlers, OAuth routes, and token-management functionality.

The precise execution path can vary by provider and operation. The following diagram illustrates the conceptual flow; it is not a claim that every provider follows an identical runtime path.

flowchart TD
    U["User request"] --> C["Chat service"]
    C --> A["Response to user"]

    C --> R["Plugin registry"]

    R -.-> M["Connectivity and tool metrics"]
    R --> D{"Tool available and authorized?"}

    D -- No --> X["Reject or report unavailable"]

    D -- Yes --> P["Plugin tool dispatch"]
    P --> I["Integration client or handler"]
    I --> E["External provider API"]
    E --> V["Validate provider response"]
    V --> C

    classDef app fill:#EDE9FE,stroke:#7C3AED,color:#312E81
    classDef policy fill:#FEF3C7,stroke:#D97706,color:#78350F
    classDef provider fill:#D1FAE5,stroke:#059669,color:#064E3B
    classDef reject fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D
    class U,C,R,P,V,A,M app
    class D policy
    class I,E provider
    class X reject

The diagram uses conventional Mermaid flowchart syntax and restrained node styling. Validate its rendering against the project's configured Mermaid version and both documentation themes.

Execution responsibilities¶

1. Registration: The chat service registers plugin implementations during startup.
2. Discovery: Plugin definitions expose tool names, descriptions, and operation categories.
3. Availability and permissions: The registry evaluates relevant connectivity and permission information when determining tool availability.
4. Dispatch: The framework routes a tool call to its corresponding plugin implementation.
5. Provider communication: Integration clients or handlers interact with provider APIs or relevant internal integration endpoints.
6. Response handling: Results and errors return through the applicable execution path.

The exact enforcement points, response transformations, and internal service boundaries must be verified for each supported execution path.

3. Authentication and credential management¶

External integrations can require OAuth authorization, API credentials, provider tokens, or provider-specific configuration. The repository contains OAuth-related routes and token-management code, but this does not establish that all providers share the same authorization flow or token lifecycle.

For each provider, document and verify the following:

• Authentication: Supported authorization flows and account types.
• Configuration: Required environment variables and credential sources.
• Permissions: Exact OAuth scopes or API permissions.
• Consent: User authorization and consent handling.
• Token protection: Storage location, encryption, and access restrictions.
• Token lifecycle: Expiration, refresh, revocation, and invalid-token behavior.
• Isolation: User-level and tenant-level credential separation.
• Disconnection: Account unlinking and credential-removal behavior.
• Failure handling: Behavior when credentials are missing, expired, revoked, or invalid.

Safe configuration example¶

The following is an illustrative environment-variable template, not a complete provider configuration. Use only the variables actually supported by the relevant implementation.

# Illustrative placeholders only
PROVIDER_CLIENT_ID=<your-client-id>
PROVIDER_CLIENT_SECRET=<your-client-secret>
PROVIDER_REDIRECT_URI=<your-registered-redirect-uri>

Keep secrets in an approved secret-management mechanism for the deployment environment. Do not place actual secret values in Markdown, screenshots, test fixtures, or issue reports.

4. Read-only operating requirement¶

The initial approved integration scope is read-only access.

The inspected plugin implementations include read operations as well as write-capable operations. Examples include sending email or messages, creating calendar events or Jira issues, modifying labels, moving or creating Drive files, and changing sharing permissions.

The plugin framework categorizes tools using values such as READ, WRITE, DESTRUCTIVE, and UTILITY. Its permission layer also includes confirmation handling for write operations and restrictions for destructive operations.

These mechanisms alone do not establish strict read-only enforcement. A confirmation dialog is not a security boundary if a write operation remains executable after confirmation.

Required enforcement controls¶

Read-only enforcement flow¶

flowchart TD
    A["Incoming tool request"] --> B["Resolve registered tool"]
    B --> C{"Tool exists and is authorized?"}
    C -- No --> X["Reject request"]
    C -- Yes --> D{"Operation permitted by read-only policy?"}
    D -- No --> X
    D -- Yes --> E["Execute authorized read operation"]
    E --> F["Validate result and enforce data boundaries"]
    F --> G["Return permitted response"]

    classDef process fill:#EDE9FE,stroke:#7C3AED,color:#312E81
    classDef decision fill:#FEF3C7,stroke:#D97706,color:#78350F
    classDef reject fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D
    classDef success fill:#D1FAE5,stroke:#059669,color:#064E3B
    class A,B,E,F process
    class C,D decision
    class X reject
    class G success

The diagram represents the required policy behavior, not evidence that the current implementation already enforces it.

Minimum security tests¶

• Every registered write-capable and destructive tool has been inventoried.
• Write and destructive calls are rejected by backend policy.
• Confirmation flags, user prompts, and model-generated arguments cannot bypass the restriction.
• Direct, composite, and applicable MCP dispatch paths enforce the same policy.
• Unauthorized read requests are rejected.
• User A cannot retrieve User B's provider data.
• Negative tests verify that rejected operations do not reach the provider.
• Automated regression tests cover policy enforcement.

Until these checks pass, describe the system as containing read-capable integrations alongside additional write-capable code, with strict read-only compliance not yet verified.

5. Provider-specific documentation¶

Each provider page must contain an operation-level inventory. A generic statement that an integration is supported is insufficient to establish its actual capabilities or security posture.

Provider documentation directory¶

Use the individual provider pages for detailed operation matrices, configuration, testing, and troubleshooting.

Do not assume a tool is usable simply because it appears in a source file. Verify registration, dispatch reachability, credentials, provider permissions, and runtime behavior.

6. Reliability and error handling¶

External providers introduce dependencies outside WhiteLotusAI's direct control. Each integration must document its actual reliability behavior rather than inheriting assumptions from another provider's implementation.

Review and test:

• Authentication and connection failures.
• Expired, revoked, and invalid credentials.
• Network timeouts and interrupted requests.
• Provider rate limits and throttling responses.
• Pagination, result limits, and partial responses.
• Invalid or missing resource identifiers.
• Provider errors and internal error mapping.
• Retry behavior, backoff limits, and duplicate-operation risks.
• Logging that could expose credentials or user data.

Document timeout values, retry policies, and rate-limit handling only after verifying the implementation. Avoid promising retries or recovery behavior that has not been tested.

7. Data protection and privacy¶

Integration data must be processed according to the application's authorization, data-protection, and retention requirements.

The implementation review must establish:

• Which provider data is retrieved and passed to the language model.
• Whether retrieved content is persisted, and where.
• Whether credentials and tokens are protected in transit and at rest.
• Whether user and tenant boundaries are enforced across requests and stored data.
• Whether logs, traces, metrics, and error reports may contain sensitive information.
• How account disconnection, token revocation, and deletion requests are handled.
• Which operations can modify remote user data.
• Whether provider content is treated as untrusted input when supplied to an AI model.

8. Integration testing requirements¶

Testing must cover functional behavior, authorization, failure handling, and the read-only security boundary.

Functional test checklist¶

• Plugin registration and tool discovery.
• Successful authorization and connection for each provider.
• Representative read operations for each provider.
• Missing and invalid credentials.
• Expired and revoked credentials.
• Provider errors and unavailable services.
• Pagination and rate-limit handling, where applicable.
• User-specific authorization and data isolation.
• Account disconnection and token-revocation behavior.
• Sensitive-data logging review.

Read-only security checklist¶

• Every write-capable and destructive operation is identified.
• Backend policy rejects prohibited operations.
• Confirmation cannot override the policy.
• All supported dispatch paths enforce the restriction.
• Applicable MCP execution paths respect the restriction.
• Read operations cannot bypass user authorization.
• Rejected operations do not modify remote resources.
• Regression tests run after relevant changes.

Use mocked provider responses for unit tests and controlled test accounts for integration tests. Avoid test cases that send messages to real users or modify real user data.

Recording verification evidence¶

For every test run, record the relevant details:

A test plan is not evidence of execution. Mark tests as passed only when the corresponding run and results can be verified.

9. Integration readiness checklist¶

An integration must not be declared verified until the applicable requirements have been completed and supported by evidence.

• Provider implementation and configuration reviewed.
• Authentication flow tested.
• Required scopes and API permissions documented.
• All implemented operations inventoried and categorized.
• Read-only policy enforced and tested for the intended release.
• Token refresh, expiration, and revocation behavior tested.
• Provider failures and timeouts tested.
• User-data isolation verified.
• Sensitive-data logging reviewed.
• Automated test results recorded.
• Known limitations and operational instructions documented.
• Frontend availability matches the verified implementation state.
• Provider documentation and security documentation updated.

10. Review and maintenance¶

Review this document whenever an integration is added, removed, enabled, disabled, or materially changed.

Changes to tool definitions, OAuth scopes, token handling, permission policies, provider clients, and dispatch logic must trigger a review of the affected provider documentation and relevant security tests.

The following documentation areas must remain consistent:

• Integration overview and provider-specific pages.
• Product Feature Catalogue and user-facing availability.
• Architecture and service-responsibility documentation.
• Security and read-only enforcement requirements.
• Testing Strategy and recorded verification results.
• Release notes and known limitations.

Maintenance workflow¶

flowchart TD
    A["Integration change"] --> B["Review source and permissions"]
    B --> C["Update provider documentation"]
    C --> D["Run functional and security tests"]
    D --> E{"Acceptance criteria met?"}
    E -- No --> F["Record blockers and limitations"]
    F --> B
    E -- Yes --> G["Record evidence and review"]
    G --> H["Align catalogue and release status"]

    classDef process fill:#EDE9FE,stroke:#7C3AED,color:#312E81
    classDef decision fill:#FEF3C7,stroke:#D97706,color:#78350F
    classDef blocked fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D
    classDef complete fill:#D1FAE5,stroke:#059669,color:#064E3B
    class A,B,C,D process
    class E decision
    class F blocked
    class G,H complete

11. Related documentation¶

• Architecture overview
• Documentation audit
• Testing strategy
• Security overview
• Read-only integration test plan

Maintenance note: Update this document alongside changes to provider implementations, authorization policies, and integration tests. Record the review date and verification evidence in the appropriate engineering documentation.