Castles

Effective July 15, 2026

Castles privacy policy

Castles is a distributed command-line application that processes authorized Gmail data on the user’s own device. There is no Castles account and no Castles-operated backend receiving Gmail data.

Gmail permission

Castles requests exactly https://www.googleapis.com/auth/gmail.readonly. Google classifies this as a restricted scope. The scope allows viewing Gmail messages and settings, but Castles uses only the Gmail profile, message, and history interfaces needed to identify the authorized mailbox, enumerate message changes, and retrieve messages for analysis. Castles does not use Gmail settings interfaces.

Read-only access means Castles cannot send, modify, delete, label, move, draft, or compose mail.

Gmail data Castles reads and why

During a scan, Castles may read message timestamps, selected headers, sender and reply-routing domains, visible subject and body text, and hostnames from visible or unsubscribe links. This evidence is used to discover external entities and explain indicators such as authentication, billing, subscription, commerce, support, activity, lifecycle, or marketing relationships.

Gmail metadata-only access is insufficient because it excludes message bodies and therefore cannot provide the visible wording and link-host evidence required for the declared relationship-discovery functionality.

Local processing and minimized storage

Raw RFC message bytes, addresses, local parts, subjects, bodies, HTML, complete URLs, message headers, and attachment content are handled ephemerally by a bounded local parser. Castles does not persist raw messages or attachments.

Castles stores privacy-minimized derived data in a local SQLite database: opaque provider message keys, observation times, normalized domains, signal categories and strengths, policy and explanation identifiers, scan checkpoints, and final findings. Normal results and exports omit provider message keys and mailbox addresses.

Network use and sharing

The local application connects to Google only for OAuth authorization, token refresh, Gmail scanning, or an explicitly requested online provider check. Gmail data and findings are not uploaded to Castles, the Castles website, GitHub Pages, Cloudflare, analytics services, advertising services, or any other Castles-controlled service.

Google’s OAuth and Gmail API infrastructure necessarily processes requests to grant and provide the user-authorized access. Castles does not otherwise sell, rent, disclose, or share Google user data. The maintainer has no human access to a user’s Gmail data through Castles.

OAuth authorization

OAuth access and refresh tokens are stored separately from findings in a private local regular file. On POSIX systems, Castles restricts sensitive files to mode 0600 and private directories to 0700. Refresh tokens are used only to obtain replacement read-only access tokens from Google without requiring repeated browser consent.

No advertising, telemetry, or model training

Castles has no advertising, tracking pixels, analytics, telemetry, automatic error reporting, or automatic report upload. Google user data is not used for advertising, credit decisions, surveillance, or training generalized artificial-intelligence or machine-learning models.

Google API Services User Data Policy

Castles’ use and transfer of information received from Google APIs adheres to the Google API Services User Data Policy, including its Limited Use requirements. This statement describes the application’s implemented data practices and is not a claim of certification by Google.

Retention, authorization removal, and local deletion

Retention is controlled by files on the user’s device. Castles does not retain Gmail data on a server.

  1. Run castles logout to remove the saved local authorization token. This does not delete findings or revoke the grant at Google.
  2. To revoke the grant, remove Castles from the third-party connections page in the user’s Google Account.
  3. To remove findings, close Castles and delete castles.db from the platform-native Castles state directory: ~/.local/state/castles on Linux by default, ~/Library/Application Support/castles on macOS, or %LOCALAPPDATA%\castles on Windows.
  4. To remove all local Castles configuration and state, delete both ~/.config/castles and ~/.local/state/castles on Linux by default, the Castles directory under ~/Library/Application Support on macOS, or the Castles directory under %LOCALAPPDATA% on Windows. Custom XDG locations override Linux defaults.
  5. Delete JSON or CSV exports separately from the locations the user selected when creating them.

Deleting an OAuth client JSON originally supplied by an advanced user remains that user’s responsibility; Castles never deletes the source file.

Website privacy

This static website has no forms, cookies, analytics, tracking pixels, remote fonts, third-party scripts, account creation, or OAuth callback handling. It receives no Gmail data. GitHub Pages hosts the static files, and Cloudflare provides authoritative DNS only; their ordinary infrastructure handling is governed by their own policies.

Support, privacy questions, and security reports

Follow the support page for privacy-safe contact options. Never send mailbox content, OAuth information, tokens, databases, or exports. Security vulnerabilities must use the repository’s private security-reporting channel.

Policy changes

Material changes to Gmail-data access or handling will be reflected here and in the application documentation before release. The effective date at the top identifies this policy version.