SETUP.md — Mail and Files Connector

# Setup

Use Python 3.10 or newer on macOS, Linux or Windows; no POSIX directory-descriptor APIs are used. Register `python3 /absolute/path/to/scripts/mail_and_files_connector.py` as a stdio server in your client. Set `GRAPH_TENANT_ID`, `GRAPH_CLIENT_ID`, `GRAPH_CLIENT_SECRET`, `MAIL_DEFAULT_USER`, and `SHAREPOINT_SITE` in that process environment. `SHAREPOINT_SITE` accepts a site ID or `tenant.sharepoint.com:/sites/name`; `SHAREPOINT_DRIVE` optionally selects a drive ID and avoids default-drive lookup. Grant the application the Microsoft Graph application permissions needed for the intended mail and site reads, with administrator consent. Use the narrowest available permissions and sites.

The server contacts `login.microsoftonline.com` for a client-credentials token and `graph.microsoft.com` for data. Redirects are checked on each hop and may reach only Graph or a single-label `*.sharepoint.com` content host. This version reads JSON metadata and does not intentionally download file content. Python urllib honors `HTTPS_PROXY`, `https_proxy`, `NO_PROXY`, and `no_proxy`; with none set, macOS or Windows system proxy settings may apply. A user-chosen proxy can see destination hostnames; TLS still terminates at the declared hosts with certificate verification.

Credentials remain in memory and are never logged or returned. For tests only, `GRAPH_FAKE_RESPONSES` names a synthetic JSON fixture and `GRAPH_FAKE_TRANSPORT_TEST_ACK=zero-width-lab-test-suite-only` enables a network-free transport; both are required. Never set them for live use. The server does not write local files.

The server reads the complete Graph JSON response (at most 2,000,000 bytes) before applying item and body output limits; a 50-item or body limit does not restrict upstream reads. No additional pages are fetched. Each stdin line is limited to 1,000,000 UTF-8 bytes including its newline; larger lines receive a clear error and are drained in bounded chunks. Test fixtures are read once with a 2,000,000-byte limit; malformed JSON, fixture entries, collection items, pagination metadata and message bodies are rejected explicitly.

login.microsoftonline.com receives the tenant identifier in the token URL and the client ID, client secret, scope and grant type in the request body. graph.microsoft.com receives the bearer token, configured mailbox/site/drive identifiers, search phrases, conversation/message/item IDs and relative folder names. A drive ID returned by the site lookup is sent back to Graph for subsequent requests. Redirects can send their provider-returned URL paths and queries to Graph or a single-label SharePoint host; bearer authorization is not forwarded on redirects. The operating system resolver receives destination hostnames, including hostnames from provider redirects; a configured proxy may resolve them instead. Returned data goes to the local stdio client and may be forwarded by that client.

Configured and fetched identifiers and relative folders reject traversal, encoded forms and backslashes before use in paths. Search phrases are quoted as data, so literal percent signs are accepted. Destination URLs reject raw dot segments and backslashes. The configured test fixture is the only local data file read; there is no configured local root or history store.

By Zero Width Lab (zerowidthlab.com)

License: MIT (read it).

Back to the listing