Integration Capability and Compliance Matrix¶

This document provides a consolidated inventory of the capabilities identified in the WhiteLotusAI integration source code. It distinguishes read operations from write-capable operations and defines the verification evidence required before approving a strictly read-only deployment.

1. Scope and objectives¶

The matrix serves as a shared reference for engineering, security, QA, and release management.

• Capability inventory: Identify the read and write operations represented in the inspected source.
• Permission review: Identify OAuth scopes that may permit mutations or broader access than required.
• Policy enforcement: Define requirements for blocking disallowed operations at the server boundary.
• Release verification: Track evidence for negative tests, authorization, and deployment behavior.
• Ongoing maintenance: Keep documented capabilities aligned with source code and deployed configuration.

Intended outcomes¶

2. Integration summary¶

The following table summarizes the capabilities identified during source inspection. It is an inventory, not a declaration that each operation is currently enabled or reachable.

3. Capability and permission details¶

3.1 Gmail¶

Identified read tools

gmail_query, search_emails, read_inbox, get_inbox_stats, get_email, get_thread, read_drafts, list_attachments, download_attachment, and list_labels.

Identified write-capable tools

draft_email, send_email, reply_email, forward_email, modify_labels, mark_read, mark_unread, archive_email, star_email, and trash_email.

OAuth review: The inspected scope set includes Gmail read, compose, and modify permissions.

Required action: Review scope minimization, tool registration, and every write-capable route. Verify that disallowed operations are rejected before any provider mutation.

3.2 Google Drive¶

Identified read tools

list_files, search_files, get_file, search_by_type, search_by_date, search_shared_files, search_starred_files, list_folders, and list_permissions.

Identified write-capable tools

create_folder, move_file, create_file, delete_file, rename_file, copy_file, star_file, share_file, and remove_permission.

OAuth review: The inspected scope set includes drive.readonly, drive.file, and drive.metadata.readonly.

Required action: Determine the effective access granted by the complete scope set and existing user consent. Test file mutations, folder operations, sharing changes, and permission removal independently.

3.3 Google Calendar¶

OAuth review: The inspected scope set includes calendar.readonly and calendar.events.

Required action: Block event creation and deletion in strict read-only mode, including requests that bypass the chat interface and invoke integration routes directly.

3.4 Jira¶

OAuth review: The inspected scopes include read:jira-work, write:jira-work, read:jira-user, and offline_access.

Required action: Review issue-creation paths, alternate handlers, and authorization behavior. Confirm that token refresh capability does not bypass user or operation-level authorization.

3.5 Slack¶

OAuth review: The inspected scope set includes channel/group read and history scopes, along with chat:write.

Required action: Determine whether message-writing permission can be removed for the intended deployment. Ensure that every message-sending path is denied when read-only mode is enabled.

3.6 Microsoft Teams¶

OAuth review: The inspected configuration includes read-related scopes and message-writing permissions.

Frontend status: The plugin catalogue currently declares live: false.

Required action: Independently verify backend route registration, OAuth scope requirements, tool availability, and message-sending restrictions. Do not infer runtime readiness from the frontend flag.

4. Read-only enforcement model¶

Strict read-only behavior must be enforced by trusted server-side components. The language model, frontend, and user confirmation flow must not be the final security boundary.

flowchart TD
    A["User request"] --> B["Authenticate identity"]
    B --> C{"Identity valid?"}
    C -- "No" --> X["Reject request"]
    C -- "Yes" --> D["Resolve tool and operation"]
    D --> E{"Explicitly allowlisted read?"}
    E -- "No" --> Y["Deny operation"]
    E -- "Yes" --> F["Authorize user and resource"]
    F --> G{"Access permitted?"}
    G -- "No" --> Z["Reject with safe error"]
    G -- "Yes" --> H["Call provider read operation"]
    H --> I["Return filtered result"]

    classDef decision fill:#E0E7FF,stroke:#4338CA,color:#1E1B4B,stroke-width:1.5px;
    classDef allow fill:#D1FAE5,stroke:#047857,color:#064E3B,stroke-width:1.5px;
    classDef deny fill:#FEE2E2,stroke:#B91C1C,color:#7F1D1D,stroke-width:1.5px;
    classDef process fill:#F1F5F9,stroke:#64748B,color:#0F172A,stroke-width:1px;

    class C,E,G decision;
    class H,I allow;
    class X,Y,Z deny;
    class A,B,D,F process;

The diagram uses explicit node colors and dark text for legibility in both light and dark documentation themes. Validate rendering against the installed Mermaid version before publishing.

Enforcement requirements¶

1. Explicit allowlisting: Only approved read operations may be dispatched in strict read-only mode.
2. Server-side denial: Reject write requests before calling the external provider.
3. Consistent authorization: Apply the same policy to primary, alternate, legacy, and directly accessible routes.
4. Least privilege: Request only the OAuth scopes necessary for the approved functionality.
5. Credential isolation: Use the authenticated user's own connection; never silently fall back to another user's credentials.
6. Confirmation independence: A confirmation prompt must not override the read-only policy.
7. Negative testing: Prove that rejected operations do not reach the provider.
8. Safe auditing: Record useful outcomes without exposing tokens, secrets, or unnecessary message content.

5. Verification matrix¶

Use this checklist during security review and release qualification. Keep each item marked Not verified until the required evidence has been reviewed and recorded.

Verification evidence template¶

For each check, record the following information in the project's issue tracker or release record:

Example negative-test contract¶

The following is a language-neutral test contract, not a claim that an existing project test already implements it.

def test_read_only_policy_blocks_write_operation():
    # Arrange: configure strict read-only mode and an authenticated user.
    # Act: invoke a write-capable operation through its real dispatch path.
    # Assert:
    #   - the operation is rejected;
    #   - the external provider mutation is not called;
    #   - the rejection is safely recorded.
    ...

6. Findings and follow-up actions¶

The following items are investigation areas identified by the source-review baseline. They are not claims that a vulnerability has been exploited.

• Write-capable tools and API operations are present in the inspected implementation.
• Confirmation metadata and tool-dispatch checks require review against the strict read-only requirement.
• Some integrations request scopes that include write capabilities.
• Alternate or legacy handler modules require a route-reachability review.
• Token fallback behavior and user-specific credential isolation require integration testing.
• Frontend readiness flags must not be treated as evidence of backend enforcement.
• Automated tests must cover successful reads and the rejection of every disallowed mutation.

Recommended remediation sequence¶

flowchart TD
    A["Inventory tools and routes"] --> B["Define read allowlist"]
    B --> C["Enforce server-side policy"]
    C --> D["Review OAuth scopes"]
    D --> E["Run negative and isolation tests"]
    E --> F{"Evidence passes?"}
    F -- "No" --> G["Track defects and remediate"]
    G --> C
    F -- "Yes" --> H["Security review and release approval"]

    classDef work fill:#E0E7FF,stroke:#4338CA,color:#1E1B4B,stroke-width:1.5px;
    classDef pass fill:#D1FAE5,stroke:#047857,color:#064E3B,stroke-width:1.5px;
    classDef fail fill:#FEE2E2,stroke:#B91C1C,color:#7F1D1D,stroke-width:1.5px;

    class A,B,C,D,E work;
    class F fail;
    class G fail;
    class H pass;

7. Release acceptance criteria¶

Strict read-only compliance should be approved only when all applicable criteria have documented evidence.

• The approved read-operation allowlist is explicit and reviewed.
• Every identified write-capable tool is unavailable or rejected under the approved policy.
• All reachable write-capable API routes enforce the policy independently of the frontend.
• OAuth permissions have been reviewed and minimized where supported.
• Cross-user credential and authorization tests pass.
• Alternate and legacy routes have been reviewed and tested.
• Negative tests confirm that rejected operations do not invoke provider mutations.
• Errors and audit records meet the project's secret-redaction requirements.
• End-to-end tests pass against the intended deployment configuration.
• A designated reviewer has approved the evidence and documented any accepted residual risks.

8. Maintenance and ownership¶

Update this matrix whenever any of the following changes:

• An integration tool, API route, or provider capability is added, removed, or modified.
• OAuth scopes, token handling, or consent configuration changes.
• Tool registration, dispatch, or authorization logic changes.
• Frontend integration readiness declarations change.
• A security test identifies a new bypass or regression.
• Deployment configuration changes the effective permissions or reachable routes.

During release review, reconcile this document with the current source code, registered routes, OAuth configuration, automated tests, and deployment evidence.

This matrix is a documentation and review aid. It does not itself enforce read-only behavior and must not be presented as a security certification.