Read-Only Integration Security Policy¶

This policy defines the security boundary for read-only integrations in WhiteLotusAI. It establishes which provider operations may be executed, where enforcement must occur, how user and connection isolation must be maintained, and what evidence is required before release.

Policy status: Security requirements baseline
Applies to: Gmail, Google Calendar, Microsoft Teams, Jira, Google Drive, and Slack
Primary enforcement boundary: Server-side integration execution
Verification requirement: Source review and automated tests

1. Purpose and scope¶

WhiteLotusAI connects AI-assisted workflows to external services that may contain confidential messages, calendar events, files, issues, and collaboration data.

Read-only access is intended to let an authenticated user retrieve and inspect information they are authorized to access without allowing the application to change the state of connected services.

This policy applies to:

• AI tool registration, selection, and dispatch.
• Integration service HTTP endpoints.
• Internal service-to-service communication.
• RPC handlers, worker consumers, and message-based execution.
• Provider clients, token management, and OAuth authorization.
• Legacy handlers and alternate execution paths that remain reachable.
• Security logging, error handling, automated testing, and release approval.

The policy applies regardless of whether an operation originates from a user interface, an API request, an AI-generated tool call, or an internal service.

1.1 Security objectives¶

The implementation must:

1. Allow only explicitly approved read operations.
2. Reject write operations before any provider-side mutation can occur.
3. Apply consistent enforcement across every reachable execution path.
4. Reject unauthorized requests by default.
5. Bind provider access to the authenticated user and intended connection.
6. Request and retain only the permissions and credentials necessary for approved functionality.
7. Log security-relevant denials without exposing secrets or unnecessary user content.
8. Provide automated evidence that denied operations never reach provider clients.

2. Read-only security model¶

A read-only operation must not modify external provider state or cause an externally visible state-changing side effect.

Examples of potentially permitted operations include listing resources, searching records, retrieving message contents, reading event details, inspecting issue metadata, and retrieving file metadata. Each operation remains subject to provider permissions, application authorization, and implementation verification.

The following operations are prohibited:

• Sending, replying to, or forwarding messages or emails.
• Creating drafts, issues, events, files, folders, or messages.
• Updating, editing, transitioning, or deleting records.
• Archiving, trashing, starring, or changing read/unread status.
• Moving, copying, renaming, or modifying files.
• Sharing resources or changing access permissions.
• Adding or removing labels, memberships, or other resource associations.
• Any other operation that changes provider state.

An operation is not read-only merely because its name includes get, list, read, or search. Its implementation, HTTP method, provider API behavior, and side effects must be examined.

2.1 Request execution and enforcement¶

The required execution model is:

flowchart TD
    A["User Request or AI Tool Call"] --> B["Authenticate Request"]
    B --> C["Resolve User and Connection"]
    C --> D["Resolve Requested Operation"]
    D --> E{"Explicitly Allowed Read Operation?"}

    E -->|No| F["Deny Request"]
    F --> G["Record Security Event"]
    G --> H["Return Policy Error"]

    E -->|Yes| I["Authorize User and Resource"]
    I --> J{"Authorization Succeeds?"}

    J -->|No| F
    J -->|Yes| K["Execute Provider Read"]
    K --> L["Validate and Filter Response"]
    L --> M["Return Authorized Data"]

    classDef request fill:#e8f0fe,stroke:#4285f4,color:#172554
    classDef policy fill:#fef3c7,stroke:#d97706,color:#78350f
    classDef denied fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
    classDef allowed fill:#d1fae5,stroke:#059669,color:#064e3b

    class A,B,C,D request
    class E,I,J policy
    class F,G,H denied
    class K,L,M allowed

The diagram describes the required control flow, not a claim that the current implementation follows every step.

Required invariant: A request that fails authentication, operation policy, or authorization must not invoke a provider operation.

3. Mandatory enforcement controls¶

3.1 Explicit server-side allowlist¶

The application must maintain an explicit allowlist of permitted integration operations.

• Deny by default.
• Approve operations individually.
• Evaluate the operation before invoking a provider client.
• Do not infer authorization from tool descriptions, user prompts, or model-generated metadata.
• Do not permit a confirmation flag to override read-only policy.
• Require security review before adding a new operation to the allowlist.

An operation absent from the approved inventory must be rejected until it has been reviewed and explicitly authorized.

3.2 Enforcement across all execution paths¶

Read-only enforcement must cover every reachable route through which provider operations can be executed.

Frontend restrictions are useful for user experience but must never be the primary authorization boundary.

3.3 Fail-closed authorization¶

When the application cannot determine whether an operation is permitted, it must reject the request.

This includes:

• Missing, invalid, or untrusted user identity.
• Missing or invalid internal service credentials.
• Unknown operation names.
• Failed or indeterminate authorization checks.
• Missing connection ownership information.
• Unexpected errors in security-critical policy evaluation.

The implementation must not fall back to shared credentials, a less restrictive handler, or an alternate execution path after an authorization failure.

3.4 Identity and connection isolation¶

Every provider operation must use credentials associated with the authenticated user and the intended provider connection.

The implementation must prevent:

• One user's provider token from being used for another user's request.
• Caller-supplied user identifiers from being trusted without authentication and authorization.
• Access to another user's connection through manipulated connection IDs.
• Unauthorized access to resources beyond the user's provider permissions.
• Shared credentials from bypassing per-user authorization requirements.
• Access tokens or refresh tokens from appearing in API responses or logs.

Internal service authentication and user-level authorization are separate requirements. Passing one check does not satisfy the other.

4. Integration-specific policy¶

The following matrix defines the intended operation boundaries. It is a policy baseline, not a declaration that every listed operation is currently implemented.

4.1 Operation classification¶

Before an operation is approved, engineering must record:

• Integration and provider API operation.
• Application tool name, route, or handler.
• Provider-side effects, including indirect effects.
• Required OAuth scopes and resource permissions.
• Authentication and authorization path.
• Allowlist entry and policy decision.
• Automated positive and negative test coverage.

A provider operation that appears read-only must be rejected if its side effects have not been established.

5. OAuth and provider permissions¶

Apply the principle of least privilege when requesting and using provider permissions.

Required engineering activities:

1. Inventory the OAuth scopes requested by each integration.
2. Map each scope to the functionality that requires it.
3. Identify write-capable or unnecessarily broad scopes.
4. Reduce scopes where supported by the provider's authorization model.
5. Determine whether existing connections require renewed consent after scope changes.
6. Verify token refresh, expiration, revocation, and reconnection behavior.
7. Ensure token retrieval and refresh are bound to the correct user and connection.
8. Prevent credentials from appearing in frontend payloads, logs, error messages, or documentation examples.

5.1 Token lifecycle requirements¶

6. API and service-layer implementation¶

Maintain an inventory of integration routes, provider clients, tool definitions, internal handlers, and worker consumers.

For each write-capable operation:

• Reject the request before provider execution.
• Return a consistent policy-denial response.
• Ensure the provider client is not called after denial.
• Apply equivalent restrictions to internal and alternate execution paths.
• Record the denial without exposing sensitive request or credential data.

Where practical, centralize operation-policy evaluation to reduce inconsistent checks and prevent newly introduced tools from bypassing enforcement.

6.1 Illustrative enforcement pattern¶

The following Python example demonstrates the intended fail-closed behavior. It is a reference pattern, not a claim that these names or functions exist in the current WhiteLotusAI source.

from collections.abc import Awaitable, Callable
from typing import Any

READ_ONLY_OPERATIONS = frozenset({
    "gmail.search_messages",
    "gmail.read_message",
    "calendar.list_events",
    "jira.search_issues",
    "drive.list_files",
    "slack.read_channel_history",
})


class PolicyDeniedError(Exception):
    """Raised when an operation is not permitted by policy."""


async def execute_read_operation(
    operation: str,
    handler: Callable[[], Awaitable[Any]],
) -> Any:
    """Execute only explicitly approved read operations."""

    if operation not in READ_ONLY_OPERATIONS:
        raise PolicyDeniedError(
            "The requested operation is not permitted."
        )

    # User identity, connection ownership, and resource-level
    # authorization must also be validated before this call.
    return await handler()

This example illustrates an operation allowlist only. A production implementation must also enforce authenticated identity, connection isolation, resource-level authorization, safe logging, and restrictions at every reachable execution boundary.

7. Logging, monitoring, and error handling¶

Record security-relevant events with enough information to investigate policy violations and authorization failures.

Recommended event fields include:

• Timestamp and correlation identifier.
• Integration and operation identifier.
• Outcome and structured denial reason.
• Authenticated principal identifier, subject to logging policy.
• Connection reference, using a non-secret identifier.
• Service or handler responsible for the decision.

Do not log:

• Access tokens or refresh tokens.
• Client secrets or authorization codes.
• Full authorization headers.
• Unnecessary email, message, calendar, issue, or file contents.
• Raw provider responses that may contain secrets or confidential information.

Return controlled errors to callers. Error responses must not expose credentials, internal secrets, sensitive provider payloads, or details that could facilitate an authorization bypass.

Monitoring should make repeated denied write attempts and unexpected authorization failures available for investigation.

8. Required automated verification¶

Automated tests must demonstrate both that approved reads can execute for authorized users and that prohibited writes cannot reach provider clients.

8.1 Test implementation requirements¶

Use mocked provider clients for unit tests and controlled test accounts for integration tests.

Negative tests must assert both the returned result and the absence of provider execution. An HTTP error response alone is insufficient evidence if the provider request may already have occurred.

For every denied operation, verify that:

1. The policy rejects the operation at the required execution boundary.
2. The provider client is not invoked.
3. No alternate handler executes the operation.
4. The denial is logged safely where required.
5. The response does not disclose secrets or sensitive provider content.

Where possible, include tests that enumerate the registered tools and reachable provider handlers, ensuring every operation has an explicit classification.

9. Release acceptance criteria¶

Read-only mode is ready for release only when all mandatory criteria have been verified.

• All six integrations have a documented operation inventory.
• Every approved read operation has a documented authorization path.
• Every write-capable operation is blocked server-side.
• AI dispatch, HTTP routes, RPC handlers, workers, and alternate paths are covered.
• User identity and connection ownership are validated.
• Cross-user access and credential isolation tests pass.
• OAuth scopes have been reviewed for least privilege.
• Token refresh, expiration, revocation, and failure handling are tested.
• Logs and error responses have been reviewed for sensitive-data exposure.
• Negative tests prove denied writes never reach provider clients.
• The automated test suite passes in the intended deployment configuration.
• Documentation reflects observed and verified implementation behavior.

10. Evidence and audit record¶

Maintain an implementation evidence record for each integration.

A control should be marked Verified only when the implementation evidence and required test results support that conclusion. If evidence is missing, record the control as Pending verification rather than assuming compliance.

11. Maintenance and change management¶

Review this policy whenever an integration introduces or changes:

• A tool, provider API operation, route, or handler.
• OAuth scopes, permissions, or token-management behavior.
• An internal RPC interface, worker consumer, or service execution path.
• Provider client behavior or response processing.
• Authorization logic, connection ownership, or resource access rules.

Any change that introduces a write-capable operation requires an explicit policy review before release. It must not become available in read-only mode through an unreviewed registry entry, fallback handler, or alternate API path.

Update the operation inventory, automated tests, implementation evidence, and documentation whenever verified behavior changes.

12. Related security documentation¶

Review this policy alongside:

• Security Overview
• Threat Model
• API Authentication
• API Error Handling

These references should be kept aligned with the implementation and the wider WhiteLotusAI security baseline.

Policy principle: Read-only access is an enforced server-side security property, not a user-interface setting or an assumption about AI behavior.