Security & trust specification

Zero-write source access and encrypted token storage

Every token, password, and remembered fact in Bitsy is protected by verifiable server-side cryptography and narrow OAuth scopes.

01 · Upstream sources
Read-only OAuth scopes
gmail.readonly · drive.readonly · calendar.readonly · linear:read
Write access: none
02 · Isolated vault
Sealed per-user store
AES-256-GCM tokens · scrypt + SHA-256 auth · user_id isolated SQLite
03 · MCP 2025-06-18
Scoped AI assistants
OAuth 2.1 + PKCE (S256) · Single-use refresh rotation
One-click revoke anytime
Layer 01

Strict read-only source scopes

Bitsy only requests read scopes from your apps. It cannot send emails, edit Notion pages, comment on Linear issues, or post to Slack.

Implementation
Provider OAuth apps request gmail.readonly, calendar.readonly, drive.readonly, Linear read, and user-approved Notion pages.
Guarantee
Every provider consent screen lists the exact read-only permissions before you approve access.
Layer 02

AES-256-GCM credential sealing at rest

Third-party OAuth access and refresh tokens are encrypted with authenticated AES-256-GCM using a dedicated key stored outside the SQLite file.

Implementation
Every token is sealed with a fresh 12-byte random IV and GCM authentication tag via BITSY_SECRET_KEY or a mode-0600 key file.
Guarantee
A copy of bitsy.db alone exposes zero usable upstream provider tokens.
Layer 03

OAuth 2.1 + PKCE and rotating tokens

AI assistants connect over OAuth 2.1 with mandatory S256 PKCE verification, 1-hour access tokens, and single-use rotating refresh tokens.

Implementation
Access tokens, refresh tokens, auth codes, and session cookies are stored solely as SHA-256 hashes — plaintext tokens never persist.
Guarantee
Reusing an old refresh token fails immediately, and removing an assistant invalidates its entire token family at once.
Layer 04

Per-user isolation and instant deletion

Every document, extracted fact, conversation, and lookup log is partitioned by user_id, with strict HTTP headers and one-click removal.

Implementation
Passwords use random-salted scrypt with timingSafeEqual; web responses enforce nonce CSP, HttpOnly cookies, and open-redirect checks.
Guarantee
Clicking Forget archives a fact immediately so no assistant receives it again, and disconnecting purges source access.

Cryptographic & protocol specifications

Connector token cipher
AES-256-GCM

12-byte random IV + 16-byte auth tag per credential

Password hashing
scrypt + timingSafeEqual

16-byte random salt, 64-byte derived key

Session & MCP tokens
SHA-256 digest only

32-byte random secrets; raw tokens never written to SQLite

AI client handshake
OAuth 2.1 + PKCE (S256)

60 min access TTL · single-use 60 day refresh rotation

Browser hardening
Nonce CSP + HttpOnly

Strict-dynamic script nonce, frame-ancestors none, nosniff

Data ownership
Zero model training

Facts stay in your vault and are never used to train external models

Exact OAuth scopes requested per app

Inspect what Bitsy requests from each provider before connecting.

AppWhat Bitsy readsRequested scopesUpstream write access
Gmail
Recent emails from the last 90 days, excluding promotions and spam.
gmail.readonlyopenidemail
None
Google Calendar
Events from the past 30 days and the next 60 days.
calendar.readonlyopenidemail
None
Google Drive
The text of your most recently edited Google Docs.
drive.readonlyopenidemail
None
GitHub
READMEs of your recent repositories and your recent issues and pull requests.
read:userrepo (read-only sync)
None
Notion
The text of pages you share with Bitsy, most recently edited first.
notion.readonlyowner=user
None
Slack
The last 30 days of messages in channels you belong to.
channels:historychannels:readgroups:historygroups:readusers:read
None
Linear
Your most recently updated issues and their status.
read
None
LinkedIn
Your LinkedIn profile details (and posts when social read access is granted).
openidprofileemail
None