Expand description
Updating members’ account recovery keys after their V1 to V2 upgrade.
A V1 to V2 upgrade rotation does not re-encapsulate the member’s account recovery key, because that requires trusting a server-supplied organization public key and the upgrade shows the member no prompt. The rotation writes a V2 upgrade token to the membership instead, and the organization keeps an account recovery key that wraps the member’s V1 user key.
The token carries both user keys, each one wrapped with the other, so opening the V1 user key yields the V2 one:
OrganizationPrivateKey -> AccountRecovery -> V1 user key
V1 user key -> V2UpgradeToken -> V2 user key
V2 user key + OrganizationPublicKey -> new AccountRecoveryAn owner or admin runs
OrganizationUsersManagementClient::upgrade_pending_account_recovery_keys
for each organization whose key it holds. The server returns the pending memberships one page
at a time. The client sends the upgrades of each page to the server before it reads the next
page. For each membership, the client:
- decapsulates the stored account recovery key into the member’s V1 user key,
- unwraps the V2 user key from the upgrade token, which cross-validates both halves,
- compares the key id of that user key with the one the server reported,
- encapsulates the V2 user key to the organization.
The server reports the user key id and can name any key. It holds none of the member’s user keys, so step 3 takes the key id of the user key the client recovered and compares it against the reported one. A mismatch means the membership names a user key the upgrade token does not carry.
A membership is sent to the server without a key when its account recovery key or upgrade token is missing, malformed, does not decrypt, or carries a user key other than the reported one. That unenrolls the member from account recovery and drops a key that no longer opens the member’s vault. A retry would read the same keys and fail again, so the membership would otherwise stay pending on every run. A membership that fails for any other reason is not sent and stays pending.
Structs§
- Pending
Page 🔒 - One page of pending memberships.
Enums§
- Account
Recovery V2Upgrade Error - Errors returned when upgrading members’ account recovery keys.
- Pending
Membership 🔒Error - Errors that stop one pending membership from being upgraded. They do not fail the organization’s upgrade: the membership is either unenrolled from account recovery or left pending.
Functions§
- fetch_
pending 🔒 - Reads one page of pending memberships.
- has_
account_ 🔒recovery_ permissions - Whether the account’s role lets it read the organization’s private key and set members’ account recovery keys. The server accepts only owners and admins.
- make_
new_ 🔒account_ recovery_ key - Reads the V2 user key out of the membership’s upgrade token and encapsulates it to the organization as the member’s new account recovery key.