mirror of
https://github.com/bretzel-app/crumbs.git
synced 2026-10-12 12:06:57 +02:00
Frederic CabassutandClaude Opus 5
4812eaf1ed
Issue #77 was caused by these docs. FEATURES.md promised "Reset passwords for any user" when no such control existed, so a user reasonably filed a bug against a promise the software never made. The docs were describing the API surface, not the UI. Now that the control ships, they describe what it actually does — and the same audit turned up three neighbouring claims that were already wrong. Corrected: - "Reset passwords for any user" — it is any user other than yourself, whose account signs in with a password, and Crumbs generates the password and shows it once rather than the admin choosing one. - "Revoke all sessions ... for any user" — Revoke has always been self-excluded in the UI. Wrong before this feature existed. - The AUTH.md sentence covering both capabilities in one breath, so fixing only the reset half would have left the revoke half wrong. - Two references to a "Settings > Users > Invite User" affordance that does not exist; the section is headed Create User. Same defect as #77 — documentation promising UI that was never built — one of them buried in the Authentik setup guide. Newly documented, all previously silent: - The sole-admin dead end, and its bound. There is no forgot-password flow, the reset control excludes your own row, and Profile requires your current password. Another admin can reset you. Failing that, an OAuth sign-in recovers the account when a provider is configured and the email matches — at the cost of handing the account to that provider permanently. Only with no second admin and no provider is there genuinely no way back in through the app. An earlier draft stated that absolutely, which would have pushed an operator toward restoring from backup when one OAuth sign-in would have done. - The OAuth pre-link trap: a password set during invite works only until the first OAuth sign-in, which hands the account to the provider. Ticking OAuth-only avoids the surprise. Tracked for a real fix in #78. - That the reset notification is best-effort. Both layers swallow send errors, so a successful reset is not evidence the user was told. - That a displayed password is only good until that account's password changes again, by any route, with nothing marking it stale. - That an unconfirmed reset shows the password anyway, and that one should be kept and retried. - That the control is also unavailable while a password is on screen — the one unavailable state that shows no reason, so an admin meeting a dead button has somewhere to look. No openapi.yaml or API.md change: neither documents /api/admin/* at all, so the new 400 needs no spec edit and pnpm docs:api regenerates nothing relevant. That gap predates this work. Verified: pnpm check 0 errors / 14 pre-existing warnings. Every factual claim traced to code by the author and again by an independent reviewer, which is how the false recovery claim was caught. Reviewed-by: adversarial-review (13 of 14 claims verified true on the first pass; failed for one false absolute, since bounded) Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RbqJcFofZSbhbGwUwZP3wU
Crumbs by Bretzel
A self-hostable, offline-first note-taking app that respects your privacy. Part of the Bretzel app universe.
Install
Docker (Recommended)
docker compose up -d
Open http://localhost:3000 and create your admin account on first visit.
With SSO (optional)
# docker-compose.yml
services:
crumbs:
image: ghcr.io/bretzel-app/crumbs:latest
ports:
- "3000:3000"
volumes:
- crumbs-data:/data
environment:
- ORIGIN=https://notes.example.com
- AUTH_OIDC_ISSUER=https://authentik.example.com/application/o/crumbs/
- AUTH_OIDC_CLIENT_ID=your-client-id
- AUTH_OIDC_CLIENT_SECRET=your-client-secret
- AUTH_OIDC_DISPLAY_NAME=Authentik
restart: unless-stopped
volumes:
crumbs-data:
Google and GitHub OAuth are also supported. See docs/AUTH.md for all providers and setup guides.
With Email Notifications (optional)
Add SMTP settings to enable email notifications (share alerts, welcome emails, security alerts):
environment:
- SMTP_HOST=smtp.example.com
- SMTP_PORT=587
- SMTP_USER=your-username
- SMTP_PASS=your-password
- SMTP_FROM=Crumbs <noreply@example.com>
Auto-enabled when SMTP_HOST is set. Users can opt out in Settings > Preferences. See docs/DEPLOYMENT.md for details.
Manual (Node.js)
git clone <repo-url> crumbs && cd crumbs
pnpm install
pnpm build
DATABASE_URL=./data/crumbs.db ORIGIN=http://localhost:3000 node build
Development
pnpm install
pnpm dev
Run make help to see all available commands, or use pnpm directly:
pnpm test # Unit + E2E tests
pnpm check # Type checking
pnpm build # Production build
Features
- Rich notes with Markdown, checklists, image attachments, and 12 color themes
- Organize with #tags, pinning, archive, and trash
- Full-text search across titles, content, and tags
- Note version history — browse and restore previous versions
- Share notes with other users on the same instance
- Email notifications for shares, security alerts, and account events (optional SMTP)
- PWA — installable, works offline via IndexedDB + LWW CRDT sync
- MCP server — let AI assistants (Claude Code, etc.) manage your notes
- Multi-user auth (Argon2) with optional OAuth/SSO (Google, GitHub, OIDC)
- Docker deployment with a single command
See docs/FEATURES.md for detailed feature documentation.
Tech Stack
| Layer | Technology |
|---|---|
| Framework | SvelteKit 2 (Svelte 5 runes) |
| Language | TypeScript (strict) |
| UI | Tailwind CSS 4 |
| Database | SQLite (better-sqlite3) + Drizzle ORM |
| Client DB | IndexedDB (idb) |
| Sync | LWW CRDTs |
| Auth | Argon2 + session cookies |
| Testing | Vitest + Playwright |
| Container | Docker (multi-stage) |
| CI/CD | GitHub Actions |
Documentation
| Document | Description |
|---|---|
| Features | Detailed feature list and behavior |
| Architecture | Local-first sync design, tech rationale, DB schema |
| Auth | Password auth, OAuth/SSO setup (Authentik, Keycloak, etc.) |
| Deployment | Docker, Node.js, reverse proxy, backups, env vars |
| API | REST API reference (auto-generated) |
| Contributing | How to contribute |
| Security | Vulnerability reporting policy |
| Changelog | Release history |
CI/CD
- CI — lint, type check, unit tests, E2E tests, Docker build on every push/PR
- Release — builds and pushes Docker image on
v*tags
Configure registry via GitHub Secrets: REGISTRY_URL, REGISTRY_USER, REGISTRY_TOKEN.