From 5c03fabd6b4f41baf9f9a7bd5596c320a0dbe1c4 Mon Sep 17 00:00:00 2001 From: Rasmus Neikes Date: Thu, 28 May 2026 22:14:28 +0200 Subject: [PATCH] root claude.md and structure complete --- claude.md | 153 ++++++++++++++++++++++++++++++++++++++++++++ crypto.md | 1 + extension/claude.md | 1 + flows.md | 1 + mobile/claude.md | 1 + sdk/claude.md | 1 + server/claude.md | 1 + website/claude.md | 1 + 8 files changed, 160 insertions(+) create mode 100644 claude.md create mode 100644 crypto.md create mode 100644 extension/claude.md create mode 100644 flows.md create mode 100644 mobile/claude.md create mode 100644 sdk/claude.md create mode 100644 server/claude.md create mode 100644 website/claude.md diff --git a/claude.md b/claude.md new file mode 100644 index 0000000..88c77ac --- /dev/null +++ b/claude.md @@ -0,0 +1,153 @@ +# 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 saftey seems like a natural choice to store user data and secrets. Harsware 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 explicitely 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 transmision of that data neets to run across secure channels - where "secure" means safe from encryption attempts for the foreseeable future, assumming adversaries with access to uantum computing. For gybbr, specfically, 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 servr 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 websire whilst in use. Essentially, mimicking the core functionality of CryptoKey in the WebCRypot API. The WebCrypto API itself was deemed insufficient, as it does not yet provide post uantum 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 attemps by look-alike websites could be prevents. + +The Browser Extensions is 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 broiwser 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 servr as a legitimate source of information. + +### Backend Server + +The backend server provides two main services. Account management, and communicartion relay. + +For the SaaS offered by LOCQR, participating websites need account manangement for registration, settinga, 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 stand alone website, some of the settings and other data needs to be made available to the relay-part of the system - hence the descision to treat both aspects as one single entity, at least initially. + +Mainly, however, the backend server will facilitate communication between the broiwser extension and mobile phones. Both entities have eüheremal existance in the sense that they are not provided with any reliable identitis, 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 extention - websites with an account will register their domains with the backend server; the extension can challenge the server to confirm that any websites is legitimate by providing its URL to the server. This isolates differentr websites; it prevents spoofing of the domain (since the extension can access it from outside of the website content space) and ties it more fluid information like account lifetime. + +As part of the relaying functionality, the backend server will provide and monitor differnet 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 seder. + +Soure of trust: The backend server is controlled by the entity resposnible for the project, it will communicate through SSL. It's domain and certificte will identify it. It will possess the secret key that lies at the center of all legitimacy within the system as described later. + +### JavaAScript SDK + +Embedded into a customer website (or the gybber website), it provides a well-defined interface for any communication between the website and the extension. TRhe extension will provide normal messaging to an from the website; and this will simply make these avaialbe to developers without any need for them to create their own boilerplate. + +Source of trust: The SDK is provided by the project ownners 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 LOCWR customers directly. The user accounts and services on these are the beneficators of the security provided by LOCWR. During developmtn, these websites will be represneted by a simple test site that will be ussed 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 LOCR. However, the websites can signal their legitimacy as regsitered participants of our servec throgh 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 + +Thoug 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 simly fail to act somewaht freuently. Is the user using the correct device, and app, to scan the correct R code? If the answer to any of these uestions is "no" we need to make sure that the conseuences of the mistake are ngelibile. + +Source of trust: The user owns all data, they are trusted implicitely 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) │ + └───────────────────┈ ┈ ┈───────────────────┘ + +``` + +## Structure + +The following structure of files and folders oints to the roots of the different subrojects as well as the remaining documentation. + + locqr/ + ├── claude.md ← root overview (current) + ├── crypto.md ← encryption scheme + ├── flows.md ← flows + ├── extension/ + │ └── claude.md + ├── mobile/ + │ └── claude.md + ├── sdk/ + │ └── claude.md + ├── server/ + │ └── claude.md + └── website/ + └── claude.md diff --git a/crypto.md b/crypto.md new file mode 100644 index 0000000..e302617 --- /dev/null +++ b/crypto.md @@ -0,0 +1 @@ +# Encryption Scheme \ No newline at end of file diff --git a/extension/claude.md b/extension/claude.md new file mode 100644 index 0000000..9c2bc8f --- /dev/null +++ b/extension/claude.md @@ -0,0 +1 @@ +# Browser Extension \ No newline at end of file diff --git a/flows.md b/flows.md new file mode 100644 index 0000000..1a55a2b --- /dev/null +++ b/flows.md @@ -0,0 +1 @@ +# Flows \ No newline at end of file diff --git a/mobile/claude.md b/mobile/claude.md new file mode 100644 index 0000000..f7a1d5d --- /dev/null +++ b/mobile/claude.md @@ -0,0 +1 @@ +# Mobile Companion App diff --git a/sdk/claude.md b/sdk/claude.md new file mode 100644 index 0000000..0a546d7 --- /dev/null +++ b/sdk/claude.md @@ -0,0 +1 @@ +# JavaScript SDK diff --git a/server/claude.md b/server/claude.md new file mode 100644 index 0000000..26672f9 --- /dev/null +++ b/server/claude.md @@ -0,0 +1 @@ +# Backend Server \ No newline at end of file diff --git a/website/claude.md b/website/claude.md new file mode 100644 index 0000000..a6c4606 --- /dev/null +++ b/website/claude.md @@ -0,0 +1 @@ +# Website (Test) \ No newline at end of file