Member Key Recovery Methods

Group Hosting Protocol · Common Method Conventions

group.member.recovery.submit

A current member uses a valid device to request member key recovery, replacing its own member encryption public key. The request does not change group state and awaits approval for a limited period.

Request Parameters

GroupMemberRecoveryRequest fields:

Clients are advised to save the complete request and candidate private key before submission so processing can resume after interruption. Candidate material does not overwrite current private state. When replacing a request, the client MUST retain the private key corresponding to the new request's public key.

Response Object

Processing and Errors

The relay uses the calling device's certificate to verify the complete request signature and confirms that the request's account matches the session and certificate accounts.

Invalid request structure, fixed values, account or public-key encoding, or a new public key identical to the current member public key, returns bad_request. A nonexistent group returns not_found. A request account that differs from the session or verification-certificate account, or a caller who is not a current member or is banned, receives forbidden. A concurrent change in member state returns state_conflict.

At most one key recovery request is retained per current member account in each group. While the current request is valid and the call passes all applicable checks, an HTTP or WebSocket retry with identical Canonical JSON for the complete signed request succeeds without refreshing acceptance or expiry times or sending another notification. A valid request with different content replaces the previous unprocessed request.

When creating or replacing a request, the relay atomically stores the current request, the device certificate used to verify its signature, accepted_at, and expires_at. The relay determines this finite waiting period at acceptance. Subsequent configuration changes and identical retries MUST NOT change the stored expiry. After successful persistence, it sends group.member.recovery.changed.

Submission, replacement, withdrawal, and expiry do not change the current member public key. Replacement does not retain the old request or change access intervals, the timeline, or the key version. When a member leaves, is removed, or has its request approved, the relay MUST delete its current request.

group.member.recovery.list

Request Parameters

Response Object

Each requests element contains:

The client MUST validate each record's signer_certificate according to the signature and identity rules of DeviceCertificate, use it to verify the network-bound signature of request, and confirm that request.account matches the certificate account. The certificate establishes only the signing identity used when the relay accepted the request. The client does not reconsider whether this historical request may be listed based on the certificate's current validity. At approval or rejection, the relay rechecks the current request, membership state, and calling permissions.

Processing and Errors

The owner can see all current requests. An administrator can see ordinary members' requests and its own request. An ordinary member sees only its own request. An ordinary member's result contains at most one item and therefore MUST NOT include next.

The list contains only unexpired requests visible to the caller.

An invalid request or cursor returns bad_request. A nonexistent group or unavailable state required by the cursor returns not_found. A caller who is not a current member or is banned receives forbidden.

When a locally saved request is no longer listed, the client synchronizes and verifies the management chain and reconstructs the current member public key from approval results. A candidate private key may be activated only if all of the following hold:

1. An approval event exists whose account and new public key both match the candidate.
2. Current member state still uses that public key.
3. The client-secret box matches the verified current commitment.

Approval management events and their verification certificates are retained permanently. If they are missing locally, retrieve the management history; a public key reported by the relay cannot replace approval verification.

Discard the candidate if the request was replaced, rejected, or expired without a corresponding approval.

If key-box verification fails, the candidate private key MUST NOT be activated. The member may submit a new key recovery request.

group.member.recovery.approve

Approves one or more current member key recovery requests. The owner or an administrator supplies a client-secret box for each target member.

The owner can approve any current member, including itself. An administrator can approve only ordinary members and cannot approve its own request.

Request Parameters

GroupMemberRecoveryApproval fields:

Each members element contains:

The approver MUST obtain and individually verify requests according to group.member.recovery.list, confirm that each request's account is the target member and that the approver has permission, and then use the request's member_encryption_public_key to seal the secret according to Client-Secret Boxes.

Response Object

None.

Processing and Errors

For each target account, the relay retrieves the current pending request at the time the operation takes effect, confirms that the target account, the request's account, and the request device certificate's account match, and accepts the batch only if every approval result matches its corresponding request.

Invalid fixed values, group ID, accounts, account set, new member public keys, commitment representation, or box encoding structure, an empty batch, or duplicate accounts return bad_request. A caller without approval permission, a banned caller, or an administrator attempting to approve a non-ordinary member or its own request receives forbidden. A nonexistent group, a missing current request for any account, or an expired request returns not_found. A closed group, a new member public key that differs from the current request, a supplied commitment that is no longer the group's current authoritative commitment, a target that is no longer a current member, or concurrent state changes return state_conflict.

The relay MUST first validate the entire batch of requests, certificates, approval permissions, membership state, client-secret commitment, and box encodings. It then atomically replaces all target member public keys, closes their old device access intervals, allows the devices recorded when it accepted the corresponding requests to access the group starting at this event, saves their client-secret boxes, deletes all approved requests, generates one new relay secret, advances epoch once, and appends one event containing the complete GroupMemberRecoveryApproval. If a client-secret rotation preparation exists, the same atomic commit MUST delete staged boxes for all target members in this batch according to group.secret.rotation.prepare, preserving all other boxes and the original expiry.

After successfully persisting the related state, the relay sends one group.timeline.changed and sends group.member.recovery.changed to signal changes to the affected requests.

group.member.recovery.reject

Deletes one or more current pending member key recovery requests in the same group. Permission is evaluated per item: a request belonging to the caller is withdrawn; the owner can reject other members' requests, while an administrator can reject only requests from other ordinary members.

Request Parameters

Response Object

None.

Processing and Errors

Invalid request fields or account formats, an empty array, or duplicate accounts return bad_request. A nonexistent group, a missing current request for any target account, or any expired request returns not_found. A caller who is not a current member or is banned, or any target request the caller lacks permission to withdraw or reject, results in forbidden. If any record is concurrently replaced or processed after the relay reads this batch of current requests and before it commits the operation, the relay returns state_conflict.

Once all checks pass, the relay atomically deletes all target accounts' pending records without changing members, public keys, access intervals, keys, or the timeline. If any check fails, the entire batch has no effect. After commit, the relay sends group.member.recovery.changed. Members may later submit new valid requests directly.