JëfPass
Your work. Your proof. An open-source work-record and Lightning payment-evidence passport for independent repair technicians.
Inspiration
An independent phone, laptop or appliance repair technician in Dakar rarely has one place that holds a job together. The agreed scope lives in a chat thread, the "yes, go ahead" is a voice note, the proof of payment is a screenshot in a different app, and the record of what was actually fixed is on paper or in memory. When the next customer asks "have you done this before, and did you get paid?", there is nothing portable to show.
We wanted to see whether a single narrow workflow could fix that: one technician, one customer, one job, carried as a clean record from start to finish. The hard part is honesty. A customer saying yes is not proof the work was done. Marking a job done is not proof money arrived. So the project started from one rule we refused to break: keep service facts and payment facts separate, and never let a hopeful assumption stand in for evidence.
What it does
JëfPass walks a technician and a customer through four steps and ends with a receipt anyone can check.
- Quote — the technician writes a scope, category, amount in sats and an optional due date. An optional AI assistant can draft the text, but the technician always reviews and saves it.
- Confirm — the customer opens an expiring link (or scans a QR code), reads the exact scope, and signs acceptance in their browser. No account, no app install.
- Complete — the technician records completion. The customer then acknowledges the finished work or raises a dispute. Service progress moves on its own track, untouched by payment.
- Get paid, keep proof — the technician requests an invoice from a receive-only Lightning wallet. Only when the wallet reports the incoming invoice settled and the returned preimage hashes to the original payment hash does JëfPass issue an immutable, signed receipt. That receipt can stay private, be exported, or be shared on a public passport.
Every receipt carries a canonical payload, a SHA-256 commitment and an Ed25519 issuer signature, so tampering is detectable by anyone, offline.
![]() Workbench — jobs with separate service and payment states. |
![]() Shareable link — an expiring link and QR; the customer needs no account. |
![]() Confirmation — the customer accepts the exact scope in-browser. |
![]() Verifiable receipt — SHA-256 commitment and Ed25519 signature checked in-browser. |
How we built it
- Next.js 16 (App Router) + TypeScript running on Cloudflare Workers via the OpenNext adapter with
nodejs_compat. - Cloudflare D1 as the persistent source of truth for
documents,rate_limitsandapp_secrets. Because the Workersnode:sqlitebuild is a non-functional stub, each request hydrates a request-scoped in-memory database from D1 and commits queued writes atomically with a D1 batch. Local development uses Node 24's built-in SQLite on disk, so the same code runs both places. - Receive-only Lightning via Nostr Wallet Connect (NWC). The wallet connection is scoped to receiving only, and credentials are encrypted at rest with AES-256-GCM, bound to the worker.
- Receipts are committed with SHA-256 and signed with Ed25519. Customer actions are signed with a one-time browser key scoped to the job and bound to a single-use nonce.
- Nostr carries signed customer-action proofs and, optionally, a worker-signed receipt commitment published through an external NIP-07 signer.
- Fireworks (any OpenAI-compatible endpoint) powers the optional scope drafting. It has zero authority: it cannot approve work, set payment state, or sign anything.
- IndexedDB holds non-financial job drafts offline and syncs them, deduplicated, when connectivity returns.
API handlers enforce account ownership, same-origin mutations, bounded JSON input and rate limits. The whole thing is covered by Vitest suites for signatures, state transitions, invoice validation and D1 behaviour, gated in CI alongside typecheck, production build and a dependency audit.
Challenges we ran into
- SQLite that isn't there. Cloudflare Workers ship a
node:sqlitestub that looks real and does nothing. We reworked the data layer so every request rebuilds an in-memory database from D1 and writes back in a single atomic batch, while keeping real on-disk SQLite for local dev from the same source. - Refusing to lie about money. The tempting shortcut is to mark a job paid when the wallet "probably" received it. We did the opposite: a payment is
SETTLEDonly after the preimage hashes back to the original payment hash, and any ambiguous result staysUNKNOWNand is never silently retried. - Proof without identity. A signed customer action should prove control of a browser key for one specific job, not impersonate a legal identity. Getting the scope and nonce binding right, without overclaiming what the signature means, took real care.
- Keeping two truths apart. It is surprisingly easy for "accepted", "completed" and "paid" to collapse into one checkmark in the UI. We kept them as distinct layers everywhere, including the data model and the receipt.
- Staying honest in the docs. We wrote the threat model, limitations and verification report to state plainly what is tested with mocks versus demonstrated against a live wallet.
Accomplishments that we're proud of
- A complete, tested journey from account to quote to customer confirmation to an unpaid signed receipt, running on Cloudflare Workers + D1.
- Receipts that anyone can verify in the browser or fully offline from an exported bundle, with no trust in our servers required for the integrity check.
- A receive-only NWC adapter with tests for BOLT11 validation, exact-amount checks, network checks, payment-hash matching, preimage verification and uncertain outcomes.
- A customer flow that needs no account, no app and works from a QR code — plus a bilingual English/French interface and a mobile-first layout.
- A green CI pipeline (automated tests, typecheck, production build and a production-dependency audit gate) and documentation that is careful about its own claims.
What we learned
- Separating what happened from whether you got paid is not a UI preference; it is the honest shape of the real problem, and it makes the trust story explainable in one sentence.
- "Fail closed and stay uncertain" is a feature. Treating ambiguous payment outcomes as
UNKNOWNrather than guessing is what makes the receipt worth anything. - Running Next.js on Workers means meeting the platform where it is, not where the Node docs assume it is. The D1 hydrate-and-batch pattern taught us a lot about request-scoped state.
- Cryptographic proofs are easy to over-sell. Being precise about what a signature does not prove was as important as implementing it.
What's next for JëfPass
- A genuine external Lightning settlement, end to end against a real wallet with independently checkable evidence — the one thing our fixtures deliberately do not stand in for.
- Exercising the full Nostr path: external NIP-07 signing and live relay publication of receipt commitments.
- Talking to real technicians. No user interviews, adoption numbers or pilot are claimed yet; the product hypothesis needs field validation before any metrics are reported.
- Resilience drills: crash and recovery testing around the invoice reservation and D1 write path, plus an independent security review.
- Accessibility and low-bandwidth testing on physical devices, which matters for the intended users.
Optional Lightning Payment Demo: JëfPass supports Bitcoin Lightning invoice creation and payment verification through Nostr Wallet Connect (NWC). Testers can connect an Alby Hub Signet wallet using a receive-only NWC connection to try invoice generation and payment settlement. An Alby browser extension is also supported for optional Nostr receipt signing.
Note: Signet/Testnet/Regtest only. Bitcoin Mainnet is not supported.
Built for the Dakar Bitcoin Hack 2026 as a working prototype — not a production-certified financial service. The default network is REGTEST (no real money) and mainnet is always disabled. Never present a fixture, seeded record or screenshot as a real payment.
MIT licensed. Source and full docs (architecture, threat model, verification, limitations): https://github.com/ansonj-dev/jefpass
Built With
- aes-256-gcm
- bitcoin
- bolt11
- cloudflare-d1
- cloudflare-workers
- ed25519
- fireworks-ai
- indexeddb
- lightning
- next.js
- node.js
- nostr
- nostr-wallet-connect
- openai-api
- opennext
- react
- sha-256
- sqlite
- typescript
- vitest
- web-crypto




