[!IMPORTANT]
QuanCard is a personal collection vault. It does not issue cards, move money, connect to
banks or help anyone bypass KYC or regional restrictions. This is a development preview
without an independent security audit. Read the threat model before you store
real data.
What it is
QuanCard on iPhone keeps your cards and bank accounts on the device and can sync through iCloud.
QuanCard Server is the third option: your own sync backend, plus a full web vault for any
desktop browser. Running as published, it only ever holds ciphertext:
- iPhone ⇄ server ⇄ web. Pair your iPhone once with a QR code. Edits on either side appear on
the other, encrypted end to end.
- Zero knowledge. The browser and the iPhone encrypt everything before upload. The server
stores opaque, immutable revisions and does not see a card number, a key or your password. It also
serves the web vault's code, so a compromised server could replace it; see the
threat model.
- Yours to run. One Docker Compose file with automatic HTTPS, your domain, your backups. Open
source under AGPL-3.0.
[!NOTE]
What is open source here. This repository, the self-hosted sync server and the web vault, is
open source. The QuanCard iPhone app is a commercial product and is not open source. The
protocols it speaks are documented here, so you can audit how your data is encrypted and stored.
Highlights
🔐 End-to-end encrypted
AES-256-GCM per item, keys derived with Argon2id (64 MiB) in the browser. The server verifies a
derived key and cannot reset or recover your password.
📱 Multi-device sync
The same revision protocol as the iPhone app, byte-for-byte compatible with its test vectors.
Changes from your phone show up in the browser on their own: when the tab regains focus, and
every 60 seconds while it is open.
🔗 One-scan pairing
A QR code hands the vault key to your iPhone. The pairing code is single-use, but the key inside is
long-term, so don't keep screenshots of it. The browser confirms the moment the phone
connects and follows its first sync. Both screens play the same "linked" animation.
🔀 Conflicts you can trust
No device clock ever silently picks a winner. Identical copies, for example from a re-paired phone,
are folded automatically. Real differences go to a conflict centre with a field-by-field comparison
and confirmed bulk actions.
💳 A real desktop app
Sidebar navigation by region and favourites, ⌘K command palette, side-sheet details, issuer card
colours matching the iPhone, photos re-encoded in the browser, and global routing details (IBAN,
SWIFT/BIC, ABA, sort code…).
🙈 Private by default
Card numbers show the last four digits. Expiry, cardholder and CVC need your password again.
Configurable auto-lock, a lock 60 s after the tab goes to the background, and a privacy cover in
task switchers.
👨👩👧 Family-ready
The owner invites members. Each member has a separate account and a separately encrypted vault;
the owner cannot read it through the server (as long as the server and web code are not tampered with).
🛡️ Hardened
TOTP two-step verification with recovery codes, rate limits and lockout, an append-only audit log,
a strict CSP, a non-root read-only container, and no telemetry.
Quick start
You need a Linux host with Docker, a domain that points to it, and ports 80 and 443 open.
git clone https://github.com/zoolapp/quancard-server.git && cd quancard-server
./scripts/init-env.sh vault.example.com # writes .env and prints a one-time setup token
docker compose up -d --wait # Caddy obtains the HTTPS certificate
- Open
https://vault.example.com, enter the setup token and create the owner account.
- Create a vault. It starts with a sample card; Settings → Sample data loads the full catalogue.
- Settings → Pair iPhone, then scan the code in QuanCard: Settings → Sync → Self-hosted Sync.
To try it on your own machine, run ./scripts/init-env.sh localhost && docker compose -f compose.local.yaml up -d,
then open http://localhost:8080.
📖 Getting started walks through the first hour: pairing,
members, two-step verification and backups. Deployment covers nginx,
Traefik and Cloudflare Tunnel, upgrades, and every configuration option.
Screenshots
All screenshots use synthetic test data or the built-in sample data (public test numbers that
cannot make payments).
How it works
Browser / iPhone (trusted) Your server (untrusted for content)
────────────────────────── ───────────────────────────────────
password ─Argon2id─▶ authKey ───────────────────────────▶ Argon2id(authKey) verifier
└▶ KEK ─wraps─▶ Account Key ───────────▶ wrapped Account Key
└─wraps─▶ vault key ──▶ wrapped vault key
card / account ─AES-256-GCM(vault key)─▶ revision ───────▶ opaque, immutable revisions
iPhone ◀── pairing QR code (long-term vault key, not sent through the server) ── browser
- One protocol, every client. The web client speaks the iPhone's
quancard.envelope.v1 and
sync v1 formats and reproduces the iOS test vectors byte for byte
(vectors/, packages/protocol, Apache-2.0).
Future clients such as macOS discover server features from GET /api/v1/status.
- Photos are re-encoded in the browser (EXIF stripped, ≤ 1600 px, ≤ 1 MiB), encrypted, and
stored inside the item's revision. They reach your server and your paired devices only.
- Sample data uses the same catalogue and item IDs as the iPhone app, so a sample loaded on one
device is recognised, and can be removed, on the others.
Specifications: auth v1 · pairing v1 ·
sync v1 · HTTP API (OpenAPI) ·
passkey v1 (proposal).
Security model in brief
A stolen database, backup or network capture reveals no card data. A weak password can still be
guessed offline, so use a long passphrase. The server operator sees metadata: account names, how
many revisions there are and when they were written. A malicious or compromised server could
serve modified web code, which is the limit of every browser-based end-to-end encrypted app. Run
the server yourself, keep it updated, and prefer the iPhone app on hosts you do not trust. Details
and mitigations are in THREAT_MODEL.md. Report vulnerabilities privately as
described in SECURITY.md.
Project status
| Area | Status |
|---|
| Server: accounts, 2FA, invites, sessions, audit, vault data plane, pairing, capability discovery | ✅ implemented, tested |
| Web vault: desktop shell, ⌘K, cards and accounts, photos, reveal, conflict centre, sample data, PWA | ✅ implemented, end-to-end and UI-gate tested |
| iPhone self-hosted sync: QR pairing, linked animation, identical-copy folding | ✅ implemented in the app (pending App Store release) |
| Docker image, HTTPS compose, backup and restore | ✅ verified |
| Passkeys (PRF unlock) | 📝 specified and reviewed, not implemented |
Encrypted .qvault import/export in the browser, macOS client, sync v2 (photo blobs) | 🗓 roadmap |
| Independent security audit | 🗓 planned |
Development
corepack enable && pnpm install
pnpm -r build && pnpm -r test && pnpm lint
pnpm exec playwright test e2e/vault.spec.ts # end-to-end story
UI_ACCEPTANCE=1 pnpm exec playwright test e2e/ui-acceptance.spec.ts # UI gate (run separately)
Layout: packages/protocol (Apache-2.0, isomorphic codecs) · apps/server (Fastify, node:sqlite) ·
apps/web (Preact, WebCrypto, hash-wasm) · e2e · deploy. See
CONTRIBUTING.md and CHANGELOG.md.
License
The server and the web client are licensed under AGPL-3.0-only. packages/protocol and
vectors/ are licensed under Apache-2.0, so other clients and
auditors can reuse them freely. The QuanCard name, the otter character and the app icon are brand
assets of ZOOL LLC (details). © 2026 ZOOL LLC.
