≪ View Page

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
software:monolith:user-qr [2026/01/05 01:50] – created diamondsoftware:monolith:user-qr [2026/01/05 02:22] (current) – run prettier diamond
Line 1: Line 1:
-# User QR Protocol+# User QR Encoding
  
 This document formally defines a QR Code format that encodes the minimum identifiable user information for use by other services. This document formally defines a QR Code format that encodes the minimum identifiable user information for use by other services.
Line 10: Line 10:
   - Non-critical user-personalized actions, such as printing out news for a user on a receipt printer   - Non-critical user-personalized actions, such as printing out news for a user on a receipt printer
 - NOT recommended, i.e. possible but please don't: - NOT recommended, i.e. possible but please don't:
-  - Door Badging (NOT recommended, see [Security][security])+  - Door Badging (NOT recommended, see [Security](#security))
   - Access-gating critical/dangerous machinery   - Access-gating critical/dangerous machinery
  
Line 17: Line 17:
 - Encodes at minimum the user ID and username - Encodes at minimum the user ID and username
 - Robust at allowing users to change username - Robust at allowing users to change username
-- Allow insecure/non-critical systems to obtain embedded information *without* computation/verification if needed for low-power/embedded purposes+- Allow insecure/non-critical systems to obtain embedded information _without_ computation/verification if needed for low-power/embedded purposes
 - Allow secure verification using remote server to obtain additional, more secretive information about current user (e.g., list of groups or avatar URL) - Allow secure verification using remote server to obtain additional, more secretive information about current user (e.g., list of groups or avatar URL)
 - QR Code must be small (has at most 4 eyes in most cases, rather than 9 eyes or more) - QR Code must be small (has at most 4 eyes in most cases, rather than 9 eyes or more)
  
-## QR Code Design+## Designs 
 + 
 +### QR Code
  
 The QR Code encodes a string encoded in Alphanumeric mode. The string must implement this syntax: The QR Code encodes a string encoded in Alphanumeric mode. The string must implement this syntax:
Line 39: Line 41:
 ``` ```
 CLAIMS_PART := USER_ID ':' USERNAME_BASE32 ':' USER_ROLE ':' ISSUED_DATE CLAIMS_PART := USER_ID ':' USERNAME_BASE32 ':' USER_ROLE ':' ISSUED_DATE
 +USER_ID     := /[0-9]+/
 USER_ROLE   := 'ADMIN' | 'MEMBER' | '_' USER_ROLE   := 'ADMIN' | 'MEMBER' | '_'
 ISSUED_DATE := YEAR '-' MONTH '-' DATE ISSUED_DATE := YEAR '-' MONTH '-' DATE
Line 60: Line 63:
 - The user's role is `admin`, meaning they belong in the `dma-admins` IdP group - The user's role is `admin`, meaning they belong in the `dma-admins` IdP group
 - The claims dates back to January 1st, 2026 - The claims dates back to January 1st, 2026
- 
  
 ### Signature Type and Part ### Signature Type and Part
Line 85: Line 87:
 ### Implementation and Example ### Implementation and Example
  
-The following function implements the algorithm in Go using a fake random source to generate the Ed25519 key (INSECURE):+The following function implements the algorithm in Go using a fake random source to generate the Ed25519 key (INSECURE) [aasadasds][asdasdasd]:
  
 ```go ```go
Line 118: Line 120:
 ``` ```
  
-## Frontend Server Design+### Frontend Server Design
  
-The frontend server must be able to handle `/QR` paths and perform a redirection to the Monolith API server's `GET /api/qr` endpoint.+The frontend server must be able to handle `/QR` paths and perform a redirection to the Monolith API server's `GET /api/qr` endpoint. The query string must be kept as-is.
  
-## Verification Server Design+### Verification Server Design
  
 This section is not finalized. This section is not finalized.
 +
 +Proposed endpoints:
 +
 +- `/qr/*`: same as `/QR/*`
 +- `/QR/keys.json`: returns the public keys that are used to sign
 +- `/QR/<CODE>`: redirect to user-specific page or custom URL if we don't have this feature yet. This allows any user to scan this code as normal and be redirected to a nice webpage.
 +- `/QR/<CODE>/verify`: verify the signature ONLY (any client can verify themselves using the public key).
 +- `/QR/<CODE>/claims`: verify the signature and return the additional user claims.
  
 ```sh ```sh
-curl -X GET "https://dma.space/QR/LMYTAMBMEJWWK33XNVSW653NMVXXO3LFN53W2ZLPO4RCYITNMVWWEZLSEJOQ.ED25519:V2OZNQJDFNNUJ26XOFY5SEKIG73RNGJJ7AI7YDTHD77V7VGTSXQA4MYH2KZIJT6RB7WAFZUU5DCMFEAB2KL5HZQG27HD7AZZGLPUAAI"+$ curl -X GET "HTTPS://DMA.SPACE/QR/10:MRUWC3LPNZSA:ADMIN:2026-01-01.ED25519:7CSS7U7C2BJM3Z3MXYENYNSBUWZRS3BGT4YWX4DXTMDBOWUABFBT4REZSKJ4FCVTFXCFY6A2WNOUIMIR3HHGLQT5CNA5ZABNOBPBMBY/verify" 
 +{ 
 +  "valid": true 
 +} 
 + 
 +$ curl -X GET "HTTPS://DMA.SPACE/QR/10:MRUWC3LPNZSA:ADMIN:2026-01-01.ED25519:7CSS7U7C2BJM3Z3MXYENYNSBUWZRS3BGT4YWX4DXTMDBOWUABFBT4REZSKJ4FCVTFXCFY6A2WNOUIMIR3HHGLQT5CNA5ZABNOBPBMBY/claims"
 { {
   "valid": true,   "valid": true,
-  "qr_claims": [10, "diamond", "admin"], +  "claims": {
-  "auth_claims": {+
     "sub": 10,     "sub": 10,
     "username": "diamond",     "username": "diamond",
Line 148: Line 162:
  
 However, the QR code can still be copied or stolen from others, so the whole system is not perfect and should not be used to gate access to critical things. However, the QR code can still be copied or stolen from others, so the whole system is not perfect and should not be used to gate access to critical things.
 +