ThimbleDB

ThimbleDB is a Cloudflare-first database for small, read-heavy web applications. Browsers read encrypted immutable objects through an authenticated storage broker and retain them in memory and IndexedDB caches. Writes and key grants use the same small authority.

Cloudflare Workers and R2 are the reference deployment. Azure Blob Storage, Amazon S3, and a local filesystem adapter implement the same provider-neutral ObjectStore contract.

Licensed under the Apache License 2.0.

Architecture

flowchart LR
  subgraph Browser["Browser trust boundary"]
    App["Web application"]
    Client["ThimbleDB client"]
    Memory["Decoded memory LRU"]
    IDB["Device-key-encrypted IndexedDB"]
    ScopeKey["Non-extractable scope key"]

    App --> Client
    Client --> Memory
    Client --> IDB
    Client --> ScopeKey
  end

  subgraph ReadPath["Brokered private-read boundary"]
    Domain["Authenticated object endpoint"]
    Objects["TDB1 gzip + AES-GCM envelopes"]
    Domain --> Objects
  end

  subgraph Authority["Authenticated authority boundary"]
    Auth["Authentication and scope authorisation"]
    Grant["Short-lived key grant"]
    Write["Validation and conditional write"]
    Auth --> Grant
    Auth --> Write
  end

  Client -- "Session-authorised ciphertext reads" --> Domain
  Client -- "Mutations" --> Auth
  Grant -- "Memory-only CryptoKey" --> ScopeKey
  Write -- "Encrypted objects" --> Objects

flowchart TB
  Engine["ThimbleDB protocol<br/>cache + scopes + TDB1 + conditional HEAD"]
  Contract["ObjectStore abstraction<br/>get + put + delete + list + ETag conditions"]

  Engine --> Contract
  Contract --> R2["Cloudflare R2<br/>preferred"]
  Contract --> Local["Local filesystem<br/>development"]
  Contract --> Azure["Azure Blob Storage<br/>supported"]
  Contract --> S3["Amazon S3<br/>supported"]

The stored object and encryption protocol stays the same across providers. Only bindings, credentials, and browser read authorisation differ.

Features

• framework-free browser client
• memory and encrypted IndexedDB caches
• brokered immutable object reads
• ETag HEAD revalidation and offline fallback
• access-scope-separated collection trees
• adaptive gzip before AES-256-GCM
• object-key-bound authenticated encryption
• HMAC-derived private node addresses
• authority-only conditional writes with route and document ID validation
• Microsoft Entra and generic OIDC identity mapping
• opaque revocable sessions tied to stable internal user IDs
• dual-proof identity linking and provider-role administration
• per-user and per-tenant scope grants
• retained deletion, restoration, and quiescent physical collection
• immutable snapshot and content-addressed trie collection layouts
• evidence-based layout recommendations and explicit migration
• write responses that update all open browser tabs
• Cloudflare Worker and native R2 binding
• local, Azure Blob, and S3 Node adapters
• historical key reads and an idempotent key-migration command
• Chromium, Firefox, and WebKit recovery tests
• typed package exports for the browser/core and auth APIs
• reusable Node and Cloudflare authority endpoint exports
• Docker, Wrangler, Bicep, and CloudFormation deployment paths

The browser bundle is about 35.2 KB uncompressed and 10.1 KB gzip. It ships no database runtime or WASM module.

Quick start

Install the package:

npm install thimbledb

The base install includes the browser/core APIs, authentication, Cloudflare authority, local provider, and Node authority without cloud storage SDKs. Install only the Node storage adapter your deployment uses:

# Azure Blob
npm install @azure/storage-blob

# Amazon S3 or R2 through the S3 API
npm install @aws-sdk/client-s3

Use the browser/core API from thimbledb, external identity primitives from thimbledb/auth, and the complete endpoint authority from either thimbledb/authority/node or thimbledb/authority/cloudflare. Consumers supply their own domain, storage, OIDC application, and secrets.

Follow the full quickstart for Cloudflare, Node, and browser setup. Implementation prompts provide copy-paste instructions for coding tools.

Use Should you use ThimbleDB for a vibe-coded app? for an exact fit check before integration. The database comparisons describe when D1, SQLite, Firestore, lowdb, or direct object storage is the better choice.

See Use cases for workload fit checks and complete guides for personal workspaces, tenant operations, field use, catalogues, journals, and structured AI application context.

To run a source checkout:

npm install
npm run dev

Open http://127.0.0.1:5173.

Configure Entra or a generic OIDC provider before signing in. The browser harness accepts an API access token and exchanges it for a ThimbleDB session. See Authentication.

The local provider is intended for development and one Node process. It is not a multi-process coordination backend.

For the browser harness, sample store, and benchmark commands, see Evaluation harness.

Cloudflare reference deployment

The reference deployment uses:

• one Worker for API routes, static assets, scope authorisation, and key grants
• one R2 binding for writes and maintenance
• one authenticated Worker broker for encrypted browser reads
• the application's Entra or OIDC identity layer

Start with Deploy to Cloudflare.

Performance characteristics

Published evidence includes live multi-region browser results against a private Cloudflare Worker and R2 deployment:

• evidence/r2-browser-multiregion-trie-2026-09-24.json
• evidence/r2-browser-multiregion-snapshot-2026-09-24.json

The measurements show:

• full-content caching dominates repeated-read latency
• location-only caching greatly reduces trie point-read bytes
• a single mutable collection root performs poorly under bursty concurrent writes
• monolithic compressed snapshots remain credible for small, rarely changed collections
• moving the 128-document product catalogue from trie to snapshot reduced measured cold reads by 29-53 percent across three Azure regions
• a 10-second HEAD TTL reduced warm snapshot p95 to 1.6-8.3 ms in those runs
• cold reads and external session creation still miss the original latency targets and remain documented limitations

These results do not establish better cost or latency than D1, Durable Objects, Turso, Firestore, or another managed database. See Benchmarks for methods, raw artifacts, limitations, and layout decision thresholds.

Documentation

When to use ThimbleDB

ThimbleDB is suited to small per-user or per-tenant datasets, catalogues, configuration, internal tools, and applications whose hot working set fits in browser storage.

Choose another database for relational transactions, high-frequency shared counters, large cross-tenant queries, or strict immediate revocation. Warm cached reads are fast, but cold object reads and external session creation can take seconds from distant regions. Design the first-load experience with those limits in mind.