Start here

Local development

ThimbleDB provides a loopback-only development path for evaluating the full authority and browser flow without configuring an external identity provider.

Scaffold a local web app

npx thimbledb@latest create my-notes-app
cd my-notes-app
npm run dev

Open http://127.0.0.1:5173. Open http://127.0.0.1:5173/studio/ for the same authority’s packaged management frontend.

The same application is available as the Node starter repository. For a Worker and R2 deployment, use the Cloudflare starter repository.

The generated app includes:

• local Node authority
• development identity
• encrypted user scope
• browser memory and IndexedDB caches
• typed notes collection
• equality and range indexes
• an explicit covering projection for indexed title lookup
• opt-in bounded point-read bundles
• fluent queries
• deletion and restore
• packaged same-origin Studio
• Vite frontend

Run:

npm run doctor
npm run build

Development identity safeguards

THIMBLE_DEV_IDENTITY=true is accepted only when:

• NODE_ENV is not production
• THIMBLE_PROVIDER=local
• THIMBLE_HOST is 127.0.0.1, localhost, or ::1
• THIMBLE_ALLOWED_ORIGIN uses a loopback hostname
• every configured Studio origin uses a loopback hostname

The authority fails startup when any condition is violated.

The development session endpoint is:

POST /api/auth/dev/session

It still uses an HttpOnly session, CSRF token, encrypted scope, and normal authority permissions. It does not simulate a production identity provider.

Cloudflare authority deployments do not include the development identity.

Connect the browser

After a session exists:

import { createThimbleClient } from "thimbledb";

const db = await createThimbleClient();

The factory:

• loads /api/config
• requests encrypted scope keys
• imports non-extractable AES keys
• configures object readers
• creates memory and encrypted IndexedDB caches
• handles layout generation
• clears cache state on logout

Advanced applications can still construct each component directly.

Move to production identity

Before deployment:

1. Remove THIMBLE_DEV_IDENTITY.
2. Configure Microsoft Entra or another OIDC provider.
3. Set a production allowed origin.
4. Bind only to the intended authority interface.
5. Store the master key and provider credentials in the platform secret store.
6. Run authentication, logout, scope, and deletion tests.

The authority refuses to start with the development identity in production.

Documentation diagrams

Mermaid remains the source format in repository Markdown. The static website uses content-addressed SVGs so diagram pages require no client-side rendering runtime.

After changing a Mermaid block under docs, regenerate the website assets:

npm run site:diagrams
npm run site:build

The generator pins Mermaid CLI 12.0.0, omits embedded font data, removes stale diagram assets, and writes only files referenced by the current Markdown.