Skip to content

Commit 13b06c6

Browse files
infeoinfeo
authored
Merge pull request #120 from cryptomator/feature/early-access-features
* Hub early access page * emergency access page * reworked users and groups * files-in-use feature
2 parents 5070854 + 08a7585 commit 13b06c6

30 files changed

Lines changed: 478 additions & 39 deletions

‎docs/desktop/files-in-use.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
id: files-in-use
3+
title: Files in Use
4+
sidebar_position: 18
5+
---
6+
7+
# Files in Use
8+
9+
:::info
10+
This feature is only available for [Cryptomator Hub](/docs/hub/introduction.md) vaults.
11+
:::
12+
13+
When multiple people work in a shared vault, two users might try to edit the same file at the same time.
14+
The **Files in Use** feature helps prevent accidental overwrites in this situation.
15+
16+
## When This Feature Applies {#when-this-feature-applies}
17+
18+
You can run into concurrent edits when:
19+
20+
- a Cryptomator Hub vault is used by multiple team members
21+
- the vault is synced across multiple devices
22+
- the vault is accessed over a network share
23+
24+
If another user is currently editing a file, Cryptomator can block opening that file for writing on your side.
25+
26+
:::note
27+
The usage information is passed with the files being edited.
28+
Therefore, it requires either the vault residing on shared storage (for example, a network share) or file synchronization.
29+
In the latter case, it takes around 10s until the status is synchronized to other devices (depending on the sync app).
30+
:::
31+
32+
## What You Will See {#what-you-will-see}
33+
34+
If a file is currently in use by someone else, Cryptomator shows a notification in the app.
35+
This means another device or user has an active edit session for that file.
36+
37+
<Image src="/img/desktop/files-in-use-notification.png" alt="Cryptomator notification for a file currently in use" />
38+
39+
## What You Can Do {#what-you-can-do}
40+
41+
In most cases, the best action is to wait until the other person finishes editing and then try again.
42+
43+
You can also choose to ignore the use status and continue.
44+
Use this only if you are sure it is safe, because forcing access can overwrite someone else's newer changes.
45+
46+
We recommend the following sequence when receiving a "File is in use" notification:
47+
1. Ask the person shown in the notification whether they are still editing the file.
48+
1. If they already closed the file but it is still shown as "in use", use "Ignore Use Status".
49+
1. Open a file marked as in use without checking with teammates only in exceptional situations.
50+
1. In that case, create a backup copy first to avoid losing edits.
51+
52+
## Stale Use Status {#stale-use-status}
53+
54+
The use status is cleared after some time without file updates (around 10 min).
55+
If this happens, access is possible again.
56+
This helps in cases such as device sleep, crashes, or interrupted sessions.
57+
58+
## Related Topics {#related-topics}
59+
60+
- [Synchronization Conflicts](/docs/desktop/sync-conflicts.md)

‎docs/hub/admin.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,24 @@ The following events are logged:
8080
- **Reset User Account** – A user [reset their account](your-account.md#reset-account).
8181
- **User Keys Change** – A user changed their keys. This happens when, e.g., the user [finished the account setup](your-account.md#account-setup) or when the `Account Key Changed`.
8282

83+
84+
#### Emergency Access {#event-type-emergency-access}
85+
86+
:::info Early Access
87+
This feature is currently in **early access** and will be fully available in version 1.5.0.
88+
:::
89+
90+
- **Emergency Access Setup** – A vault owner set up or updated the Emergency Access configuration for a vault (e.g. by assigning council members in Vault Details).
91+
- **Emergency Access Settings Updated** – An admin changed the global Emergency Access settings.
92+
- **Emergency Access Recovery Started** – A council member started an Emergency Access recovery process.
93+
- **Emergency Access Recovery Approved** – A council member approved a running recovery process.
94+
- **Emergency Access Recovery Completed** – A council member completed a recovery process.
95+
- **Emergency Access Recovery Aborted** – A council member aborted a running recovery process.
96+
97+
:::note
98+
When a council member starts a recovery process both `Emergency Access Recovery Started` and `Emergency Access Recovery Approved` is logged.
99+
:::
100+
83101
#### Legacy {#event-type-legacy}
84102

85103
- **Claim Vault Ownership** – A user claimed vault ownership. This event is logged when a vault created with hub pre 1.3.0 is claimed by the vault creator using the `Vault Admin Password`.
@@ -132,3 +150,30 @@ If a user resets their account, their [User Key Pair](/docs/security/hub.md#user
132150
Additionally, any existing trust chains that included the user will be broken, requiring re-verification to restore trust.
133151
:::
134152

153+
154+
## Emergency Access {#emergency-access}
155+
156+
:::info Early Access
157+
This feature is currently in **early access** and will be fully available in version 1.5.0.
158+
:::
159+
160+
This configuration defines default [Emergency Access](emergency-access.md) values for new or updated vaults.
161+
162+
<Image src="/img/hub/admin-emergency-access.png" alt="Emergency Access" width="1440" height="658" />
163+
164+
Enable `Enable Emergency Access` and configure:
165+
166+
* `Required Keys`: Number of required key shares
167+
* `Keyholders`: Default council members (only activated users)
168+
* Optional: `Let vault owners choose different keyholders`
169+
* Optional: `At least` (minimum members if owners can choose a different council)
170+
171+
:::warning
172+
A council without redundancy (`Required Keys == number of council members`) is possible, but not recommended.
173+
:::
174+
175+
:::info Enterprise Feature
176+
The following Audit Log feature is available only in the **Enterprise Edition**:
177+
178+
- Emergency Access Audit Logs
179+
:::

‎docs/hub/early-access.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
id: early-access
3+
title: Early Access
4+
sidebar_position: 10
5+
---
6+
7+
# Early Access
8+
9+
These features are currently in **early access** and will be fully available in **Cryptomator Hub 1.5.0**.
10+
11+
- [User & Group Management](/hub/user-group-management) — Manage users, groups, roles, and permissions directly in Hub
12+
- [Emergency Access](/hub/emergency-access) - Restore access to a vault in case of account loss or ownership issues

‎docs/hub/emergency-access.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
id: emergency-access
3+
title: Emergency Access
4+
sidebar_position: 9
5+
---
6+
7+
# Emergency Access
8+
9+
:::info Early Access
10+
This feature is currently in **early access** and will be fully available in version 1.5.0.
11+
:::
12+
13+
Emergency Access restores access to a vault inside Cryptomator Hub in case of account loss or ownership issues.
14+
Its process requires a group of trusted users (the "council") to approve the recovery.
15+
When enough approvals are collected, the emergency change is completed and vault management access is restored.
16+
Technically, this is implemented using key splitting based on **[Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_secret_sharing)**.
17+
18+
## Setup Emergency Access
19+
20+
The feature can be activated for new and existing vaults:
21+
22+
* **New vaults:** During vault creation, use the `Define Emergency Access Conditions` step.
23+
For the full workflow, see [Vault Management](vault-management.md#create-a-vault).
24+
* **Existing vaults:** Open `Vault Details` and [configure Emergency Access](vault-management.md#emergency-access-council).
25+
26+
## Starting a Recovery Process
27+
28+
To start, open the `Emergency Access` page, select the vault, and start the desired process.
29+
30+
<Image src="/img/hub/emergency_access_vault_list.png" alt="Emergency Access Vault List" width="2560" height="1080" />
31+
32+
There are two process types:
33+
34+
1. `Change Emergency Access Council`: Change Emergency Access council and threshold
35+
2. `Choose Vault Members`: Choose vault owners/members
36+
37+
:::info
38+
Only one running process per type is allowed for the same vault.
39+
:::
40+
41+
Use this quick guide to choose the right process:
42+
43+
| If you want to... | Start this process |
44+
| --- | --- |
45+
| Give vault access to different users (owners/members) | `Choose Vault Members` |
46+
| Remove access from specific users | `Choose Vault Members` |
47+
| Replace council members who approve emergency operations | `Change Emergency Access Council` |
48+
| Change how many council approvals are required (threshold) | Configurable in the [admin settings](../admin#emergency-access) |
49+
50+
:::note
51+
Starting a process automatically approves the process.
52+
:::
53+
54+
55+
### Choose Vault Members
56+
57+
The `Choose Vault Members` process allows you to select new vault `Owners` or `Members`.
58+
59+
Users that are no longer part of the vault are shown as `Removed`.
60+
61+
<Image src="/img/hub/emergency_access_change_permissions_start.png" alt="Emergency Access Vault List" width="2560" height="1080" />
62+
63+
64+
### Change Emergency Access Council
65+
66+
The `Change Emergency Access Council` process allows you to select a new council.
67+
68+
The minimum required number of members is configured in the [Admin settings](admin.md#emergency-access).
69+
70+
<Image src="/img/hub/emergency_access_change_council_start.png" alt="Emergency Access Vault List" width="2560" height="1080" />
71+
72+
## Approve a Recovery Process
73+
74+
To view or approve running Emergency Access processes, open the `Emergency Access` list.
75+
If for a vault an Emergency Access process is running, the vault is displayed with a process button.
76+
If you haven't approved the process, the button includes `Approve now`.
77+
78+
<Image src="/img/hub/emergency_access_vault_list_change_council_approve_now.png" alt="Emergency Access Vault List Approve Now" width="2560" height="1080" />
79+
80+
Approve a running process in three steps:
81+
82+
1. Open the vault in the `Emergency Access` list.
83+
2. Click `Approve now` to open the `Approve Emergency Access` dialog.
84+
3. Review the details and click `Approve`.
85+
86+
<Image src="/img/hub/emergency_access_vault_list_change_council_approve_dialog.png" alt="Emergency Access Vault List Approve Dialog" width="2560" height="1080" />
87+
88+
After submitting your share, the button shows `Waiting for other approvals`. You can track the ongoing process progress in the same process button and its details popover.
89+
90+
91+
You can also inspect details before approving. Hover (or click) the segment ring area on the left side of the process button to open the process details popover. The popover shows:
92+
93+
* process type and required approvals
94+
* current progress
95+
* process council members
96+
* per-member status (`Added` / `Pending`)
97+
98+
<Image src="/img/hub/emergency_access_vault_list_hover_process.png" alt="Emergency Access Vault List Hover Process" width="2560" height="1080" />
99+
100+
## Complete a Recovery Process
101+
102+
As soon as enough shares are available, the process button in the `Emergency Access` vault list shows `Complete now`.
103+
104+
<Image src="/img/hub/emergency_access_vault_list_change_council_complete_now.png" alt="Emergency Access Vault List Complete Now" width="2560" height="1080" />
105+
106+
Click `Complete now` to open the `Complete Emergency Access` dialog. In this dialog, review the process details and click `Complete Process` to finalize the recovery process.
107+
108+
<Image src="/img/hub/emergency_access_vault_list_change_council_complete_dialog.png" alt="Emergency Access Vault List Complete Dialog" width="2560" height="1080" />
109+
110+
Results by type:
111+
112+
* `Choose Vault Members`: Vault roles are updated and required access grants are redistributed.
113+
* `Change Emergency Access Council`: The old council is replaced by the new council.
114+
115+
After successful completion, the process is removed.
116+
117+
## Abort a Recovery Process
118+
119+
Running processes can be canceled in the dialog using `Abort this Process`.
120+
121+
<Image src="/img/hub/emergency_access_vault_list_change_council_abort_dialog.png" alt="Emergency Access Vault List Abort Dialog" width="2560" height="1080" />
122+
123+
124+
## Typical States and Notes
125+
126+
The following warning states can appear in the Emergency Access list:
127+
128+
* `No Vault Council Member anymore`: The user is still part of a running process but no longer part of the current vault council.
129+
What to do: Ask a current council member to start a new process with the correct council composition.
130+
* `Broken Emergency Access`: Too few valid shares remain (for example after council members reset their accounts).
131+
What to do: Reconfigure the council in vault details and ensure enough active council members can provide shares.
132+
* `No Redundancy`: No fault tolerance in the council.
133+
What to do: Increase the number of council members or reduce the required threshold so one unavailable user does not block recovery.
134+
135+
## Audit Log Events
136+
137+
See [Emergency Access Audit Log events](admin.md#event-type-emergency-access).

0 commit comments

Comments
 (0)