19 KiB
LOCQR
We want to build a distributed, post-quantum login and secret manager called locqr - a play on words locker and lock-qr, indicating the most visible feature: secure transfer of credentials or secrets from secure, encrypted storage to the website via a secure channel established by a QR code - bypassing traditional network links and minimizing attack surfaces.
The elements that need to be orchestrated for this to work are:
- browser extension
- mobile companion app
- javascript SDK for websites
- backend server
For the entire system to work, and be testable under development, two further entities need to exist; and they will sometimes be treated as integral parts of the entire ecosystem:
- user
- website (test)
Architecture
The named entities will cooperate with each other, and are best looked at as a distributed, fragmented state machine with unreliable actors.
Functions or user stories will often involve processes that span multiple entities, require multiple round trips of information flow, and the system cannot be accurately described by looking at single entities in isolation, or fragmenting coherent processes at their boundaries.
Looking at processes end-to-end, considering how and where data is changed, stages transition and control paths are chosen will allow to describe the system and its operation fully, and from there derive the artifacts that need to be built within those boundaries.
Goals
The goals of the project are multifaceted, but complement and support each other; if executed well, a single, coherent multi-artifact project will naturally achieve them all.
Strategic Goals
LOCQR was originally devised as a complement tool for a different project: GYBBR, a secure, E2EE, distributed, privacy-focused social network. The envisioned architecture of the social website gave rise to the core functions that LOCQR was going to provide. This has been extended to further enhance security, but the link between the two projects remains.
Even though not technically required, LOCQR would make GYBBR more accessible to a wider range of users; especially less technically inclined users who we hope to reach.
The decision to create LOCQR first is strategic: There is a possibility that the core functionality can be offered as an independent SaaS for websites and other services requiring secure login or management of sensitive data between devices. A financially successful LOCQR would then provide a financial pathway to tackle the much larger GYBBR.
Functional Goals
Users should be able to transfer content securely from their mobile phones, where they can be stored securely using the native platform features, into the browser extension and vice versa. The browser extension exists outside of the scope of the website; so that UX is guarded against phishing or XSS attacks. For the core functionality that boundary will be weakened slightly if the data is ultimately transferred to the website.
For GYBBR, the extension will further serve as an isolated crypto-service, providing encryption, decryption, signing and verification functions, as well as secure key storage; the website can use these services, whilst encrypted data is separated from the site itself. (Since user content will ultimately be displayed on the site, some encrypted information will be revealed; but all keys and secrets will remain strictly isolated when in their cleartext form.)
One core design principle of GYBBR is that the site owner of the social network will not have access to any user content in clear text. That, in turn, requires that no encryption secret can ever be revealed to the website.
LOCQR solves the conundrum of how users can use encryption on a website, without sharing their encryption secrets with the website.
Extending the scope of LOCQR to gain accelerated financial viability results in a lower degree of isolation with the same level of security against password theft or phishing through different out-of-band methods.
Entities
Mobile Companion App
Leveraging mobile platforms with their combination of hard- and software that is designed for data safety seems like a natural choice to store user data and secrets. Hardware vaults secure data at rest, and take care of isolating it from other apps and unauthorized users. Potentially doubles as a 2FA token - i.e. the choice to put passwords onto a separate device gives us the option to tie the device to its user and explicitly ensure that it is part of the login process. The mobile app is where data is stored at rest, and the main user stories are providing that data to the website and receiving the data from other systems to be stored in the first place. That transmission of that data needs to run across secure channels - where "secure" means safe from encryption attempts for the foreseeable future, assuming adversaries with access to quantum computing. For gybbr, specifically, password creation in dedicated formats should also be provided. (We are contemplating an abstraction of that feature that would make it available to other services as well.)
Source of trust: The mobile app is distributed through platforms like the official app stores of Apple and Google. It will have hardcoded keys that allow it to identify the central server as a legitimate source of information.
Browser Extension
At the core, we needed a way to encapsulate encryption keys away from the website, to prevent anyone from lifting encryption keys out of the gybbr website whilst in use. Essentially, mimicking the core functionality of CryptoKey in the WebCrypto API. The WebCrypto API itself was deemed insufficient, as it does not yet provide post-quantum security. Other security aspects were discovered during early planning, e.g. by providing its own UI outside of the website DOM and display boundaries, phishing attempts by look-alike websites could be prevented.
The Browser Extension is the main hub for communication, it interacts with websites - directly and through the JS SDK, with the user through its own UI. It communicates with the backend server - both as a relay and provider of information - and the mobile - directly through the display of QR codes that can be read by the phone, as well as through the backend server as a relay and security gate.
Source of trust: The browser extension will be provided through official websites, from the company or entity that lies at the core of gybbr and LOCQR. It will have hardcoded keys that allow it to identify the central server as a legitimate source of information.
Backend Server
The backend server provides two main services. Account management, and communication relay.
For the SaaS offered by LOCQR, participating websites need account management for registration, settings, payment, etc. For the purposes of development, these functions will be performed by the backend server. Whilst most of this can be provided via a standalone website, some of the settings and other data needs to be made available to the relay-part of the system - hence the decision to treat both aspects as one single entity, at least initially.
Mainly, however, the backend server will facilitate communication between the browser extension and mobile phones. Both entities have ephemeral existence in the sense that they are not provided with any reliable identities, domains or IP addresses. In order to communicate, they need a relay station with a known access point: a backend server with a fixed domain.
The server will also be used to identify websites for the extension - websites with an account will register their domains with the backend server; the extension can challenge the server to confirm that any website is legitimate by providing its URL to the server. This isolates different websites; it prevents spoofing of the domain (since the extension can access it from outside of the website content space) and ties it to more fluid information like account lifetime.
As part of the relaying functionality, the backend server will provide and monitor different one-time tokens used by the other entities; it will guard transmission from expired or invalid credentials, so that only the intended receivers can connect to communications initiated by any sender.
Source of trust: The backend server is controlled by the entity responsible for the project, it will communicate through SSL. Its domain and certificate will identify it. It will possess the secret key that lies at the center of all legitimacy within the system as described later.
Self-Hosted Delegate Server
An option planned for future website administrators is the availability of a self-hosted backend server. All of its main functions will be taken over by the delegate server: token verification, traffic relaying, etc. The sole purpose of that construct is to allow offering a paid tier of the service with unlimited usage. Since the compute costs for crypto operations on the backend server are relatively high, a free tier would otherwise result in a high risk for ourselves; whilst a per-transaction model would create a similar risk for highly popular websites with many user logins.
The technical solution here is simply to extend the per-website certificate to include an optional URL for the delegate server of that specific website; and include it under the umbrella of the backend server's signature. All communication between the main backend server and any delegate server will be independent of individual transactions. There might be an exchange of revocation notifications, or the account management could still be handled by the main server, etc.
Source of trust: Hosted by the same entity as the website that it is being used for; and authorized by the same source of the extension, the companion app, that the user is already familiar with.
Scope: For future consideration. Currently not referenced anywhere else.
JavaScript SDK
Embedded into a customer website (or the gybbr website), it provides a well-defined interface for any communication between the website and the extension. The extension will provide normal messaging to and from the website; and this will simply make these available to developers without any need for them to create their own boilerplate.
Source of trust: The SDK is provided by the project owners and as such, the security can be verified. The site is out of scope for the sake of this document: once information has been passed to the website, it has left the secure sphere of this project.
Website
This refers to the websites provided by gybbr or LOCQR customers directly. The user accounts and services on these are the beneficiaries of the security provided by LOCQR. During development, these websites will be represented by a simple test site that will be used to trigger different events and process flows.
Source of trust: External to the project. Users decide to use these websites and trust them for their own reasons. That trust is out of scope for LOCQR. However, the websites can signal their legitimacy as registered participants of our service through a token that signs their URL and an expiry timestamp with the secret key held by the backend server. This identifies the specific account; and will allow the system to guard the site from interacting with any data stored for other websites or services.
User
Though unorthodox, we chose to include the end user as part of the entire system. They participate in different processes not only by triggering specific flows but because their choices and confirmations will influence the control flow of the entire system, and because we need to be prepared for users to make mistakes or simply fail to act somewhat frequently. Is the user using the correct device, and app, to scan the correct QR code? If the answer to any of these questions is "no" we need to make sure that the consequences of the mistake are negligible.
Source of trust: The user owns all data, they are trusted implicitly and by design.
Connections
The entities can communicate via different media and channels:
┌───────────┬───────────┬───────────┬─────────────────────────────────────────┐ │ Entity A │ Entity B │ Direction │ Channel │ ├───────────┼───────────┼───────────┼─────────────────────────────────────────┤ │ User │ Website │ ↔ │ UI / air │ ├───────────┼───────────┼───────────┼─────────────────────────────────────────┤ │ User │ Extension │ ↔ │ UI / air │ ├───────────┼───────────┼───────────┼─────────────────────────────────────────┤ │ User │ Phone │ ↔ │ UI / air │ ├───────────┼───────────┼───────────┼─────────────────────────────────────────┤ │ Website │ Extension │ ↔ │ Browser messaging (JS SDK) │ ├───────────┼───────────┼───────────┼─────────────────────────────────────────┤ │ Extension │ Phone │ → │ QR code / air (session initiation only) │ ├───────────┼───────────┼───────────┼─────────────────────────────────────────┤ │ Extension │ Phone │ ↔ │ HTTPS via backend relay │ ├───────────┼───────────┼───────────┼─────────────────────────────────────────┤ │ Extension │ Backend │ ↔ │ HTTPS │ └───────────┴───────────┴───────────┴─────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────┐
│ USER │
└──────┬──────────────────────────┬──────────────────────┬─────────┘
↕ UI/air ↕ UI/air ↕ UI/air
┌────┴────┐ ┌─────┴──────┐ ┌────┴────┐
│ Website │◄─────SDK─────►│ Extension │───QR────►│ Phone │
└─────────┘ └──┬──────┬──┘ └──┬──────┘
direct↓ ↑ relay ↓relay
┌─────────────────┴─┈ ┈ ┈┴────────────────┴─┐
│ Backend ┋ Backend (relay) │
└───────────────────┈ ┈ ┈───────────────────┘
Trust and Secure Channel
In order to achieve the main goal of the project - the safe delivery of login credentials to a website - elements within the system need to trust each other. The description of the entities describes why and how they can be trusted individually, but it is important to understand how that individual trust can be assembled into a chain of trust that allows a secure connection between the extension and the mobile phone.
Trust in the system is rooted in compile-time constants. The extension and companion app each carry pinned public keys for the backend server, baked in at build time. Nothing at runtime can substitute them. All session legitimacy traces back to the backend server's ability to sign, and the clients' ability to verify against those constants.
The secure channel between extension and companion is bootstrapped through the QR code. The QR code is not itself the channel — it is a physical, air-gap-equivalent link that carries a cryptographic commitment to a one-time key bundle stored server-side, together with a backend-signed token that binds that commitment to a specific URL, run ID, and TTL. A network attacker cannot intercept what is on screen. The companion verifies the backend's signature before touching anything else.
Once the companion has fetched and verified the one-time key bundle — atomically, exactly once, from the backend — it performs a hybrid classical/post-quantum key encapsulation. Both sides independently derive the same session key. A six-digit code derived from that key is displayed on both devices simultaneously; the user confirms the match, proving both sides share the same key. From that point, all extension-to-companion traffic is end-to-end encrypted and relayed through the backend, which cannot read it.
The cryptographic primitives and exact parameters behind each of these steps are specified in crypto.md. Individual flows that use this channel are described in flows.md.
Structure
The following structure of files and folders points to the roots of the different subprojects as well as the remaining documentation.
locqr/ ├── claude.md ← root overview (current) ├── crypto.md ← encryption scheme and library choices ├── flows.md ← end-to-end flows ├── interfaces.md ← wire formats and cross-component message schemas ├── dev.md ← local development environment and setup script ├── extension/ │ └── claude.md ├── mobile/ │ └── claude.md ← native Android app + web stub; see also companion/ ├── companion/ ← web companion stub source; documented in mobile/claude.md ├── sdk/ │ └── claude.md ├── server/ │ └── claude.md └── website/ └── claude.md