Merge branch 'develop'

Author: tobihagemann

docs/security/architecture.md

@@ -139,6 +139,10 @@ The wrapped keys and the parameters needed to derive the KEK are then stored as
 }
 ```
 
+:::note
+When calculating the `versionMac`, the `version` value must be converted to a 32-bit unsigned integer and then encoded as a 4-byte big-endian representation before computing the HMAC-SHA256, regardless of the system's native byte order.
+:::
+
 When unlocking a vault the KEK is used to unwrap (i.e. decrypt) the stored masterkeys.
 
 <WhiteBox>

docs/security/hub.md

@@ -49,3 +49,37 @@ When an Account Key is suspected of being compromised, it can and should be re-g
 The Account Key itself is stored as an [ECDH-ES-encrypted JWE](https://datatracker.ietf.org/doc/html/rfc7518.html#section-4.6), allowing its owner to
 view it from any authorized device. Regardless it should be securely stored independently.
 :::
+
+## Unlock Procedure {#unlock-procedure}
+
+Vault keys are shared with users via their [User Key Pairs](#user-key-pair). Each user self-manages their devices. The [Device Key Pair](#device-key-pair) is required to decrypt the user's private key, which in turn decrypts the vault access token.
+
+<WhiteBox>
+  <Image src="/img/hub/unlock-procedure.drawio.png" alt="Hub Unlock Procedure" width="1102" />
+</WhiteBox>
+
+### Unlock Flow {#unlock-flow}
+
+The unlock procedure consists of two distinct steps that establish a key hierarchy between devices, users, and vaults:
+
+1. The client requests the vault access token from `/api/vaults/{vaultId}/access-token`. The server returns a JWE containing the vault's raw masterkey encrypted with the [User Public Key](#user-key-pair).
+2. The client requests its device-specific JWE from `/api/devices/{deviceId}`. This JWE contains the [User Private Key](#user-key-pair) encrypted with the [Device Public Key](#device-key-pair). The device uses its locally stored private key to decrypt this JWE, obtaining the user's private key, which is then used to decrypt the vault-specific JWE from step 1.
+
+This creates a cryptographic chain: Device Private Key → User Private Key → Vault Key. The intermediary user key layer allows vault keys to be encrypted once per user rather than once per device. When users add new devices, only a new device-specific JWE of the user key needs to be created, eliminating the need to re-encrypt all vault keys.
+
+### Access States {#access-states}
+
+When retrieving the vault access token from `/api/vaults/{vaultId}/access-token`:
+
+* `200 OK`: Successful retrieval of encrypted vault key
+* `402 Payment Required`: License needs upgrade
+* `403 Forbidden`: User lacks permission to access the vault
+* `410 Gone`: Vault has been archived
+* `449 Retry With`: User account exists but hasn't been properly initialized (missing key pair)
+
+When retrieving the user's encrypted private key from `/api/devices/{deviceId}`:
+
+* `200 OK`: Device is registered and authorized
+* `404 Not Found`: Device needs to be set up
+
+We still keep the legacy API endpoint `/api/vaults/{vaultId}/keys/{deviceId}` for compatibility reasons for a while. However, it will only work for existing data. Any newly registered device can only be unlocked using the new workflow.