Workspace Member Devices Proof

Workspace Member Devices Proof


For each workspace chain event the members in the workspace can be determined. This though doesn't include the devices of members. In order to create a cryptographic proof of all the members including their devices the workspaceMemberDevicesProof was created.


An alternative design would have been to have the members and devices in the workspace chain. This would have certainly simplified the design, but then the workspace chain would become a lot longer and the server would have to provide a lot more data for web clients.

The idea of this design was to have a short workspace chain and only fetch the devices information on demand when the workspaceMemberDevicesProof is references e.g. in a Document snapshot AAD.



type WorkspaceMemberDevicesProof = {
  hash: string;
  hashSignature: string;
  version: number;
  clock: number;

The hash is a hash of the WorkspaceMemberDevicesProofData and the hashSignature is a signature of the hash. The hash is used to uniquely identify entries and the hashSignature is used to verify the integrity of the data by a device of an existing workspace member.

The clock is a number that is incremented for each new WorkspaceMemberDevicesProof and is used to determine the latest WorkspaceMemberDevicesProof and also to make sure that the server can only provide newer WorkspaceMemberDevicesProof and never older ones.

The version is used to make sure that the client is aware of the latest WorkspaceMemberDevicesProof and if not the client must be updated.

Content Structure

type WorkspaceMemberDevicesProofData = {
  clock: number;
  workspaceChainHash: string;
  userChainHashes: record<userId, userChainEventHash>;

The clock is the same as in the WorkspaceMemberDevicesProof.

The workspaceChainHash is the hash of the workspace chain that should be referenced.

The userChainHashes is a map of user ids to the hash of the user chain event of each user. From each user-chain it's possible to determine the active and removed devices of the user.


There are only two functions to create and verify a WorkspaceMemberDevicesProof.

  • createWorkspaceMemberDevicesProof
  • isValidWorkspaceMemberDevicesProof

Cryptographic Dependencies and actual implementation

  • hash: sodium.to_base64(sodium.crypto_generichash(64, message))
  • canonicalize: predictable canonicalization of JSON as defined by RFC8785 (opens in a new tab)
  • sign: sodium.crypto_sign_detached(message, privateKey)
  • signVerify: sodium.crypto_sign_detached(signature, message, publicKey)


It requires the following arguments:

  • workspaceMemberDevicesProofData
  • authorKeyPair

The functions returns a proof.

hash = hash(canonicalize(workspaceMemberDevicesProofData));
hashSignature = sign(
  concat("workspace_member_devices_proof", hash),
); (opens in a new tab)


hash = hash(canonicalize(workspaceMemberDevicesProofData));
assert(hash === proof.hash);
  concat("workspace_member_devices_proof", hash),
); (opens in a new tab)

Version Checks

Each Workspace Integrity Proof is associated with a version. Is the version higher than what the current client is aware of the client will throw an error and the user must be informed to update the application.

App Integration

Creating a proof

On every event that changes adds a workspace chain entry or changes a user chain entry the client must create a new WorkspaceMemberDevicesProof and send it along with the event to the server.

The server verifies the result and stores the WorkspaceMemberDevicesProof with the related data (workspaceChainHash and userChainHashes) in the database. The server uses one re-usable function to verify the proof: (opens in a new tab). Only for creating a workspace the isValidWorkspaceMemberDevicesProof is used directly on the server.

Here a list of all event and the affected chain:

  • create workspace (workspace chain)
  • update workspace member role (workspace chain)
  • remove member from workspace (workspace chain)
  • create workspace invitation (workspace chain)
  • accept workspace invitation (workspace chain)
  • delete workspace invitation (workspace chain)
  • add device during login (user chain)
  • delete device (user chain)
  • logout (user chain - removes the current device)


Create workspace (opens in a new tab)

Server: (opens in a new tab)

Update workspace member role (opens in a new tab)

Server: (opens in a new tab)

Remove member from workspace (opens in a new tab)

Server: (opens in a new tab)

Create workspace invitation (opens in a new tab)

Server: (opens in a new tab)

Accept workspace invitation (opens in a new tab)

Server: (opens in a new tab)

Delete workspace invitation (opens in a new tab)

Server: (opens in a new tab)

Add device during login (opens in a new tab)

Server: (opens in a new tab)

Delete device (opens in a new tab)

Server: (opens in a new tab)

Logout (opens in a new tab)

Server: (opens in a new tab)

Verifying the proof

Every proof that is received by a client is verified and only then added to the local sqlite DB. (opens in a new tab) (opens in a new tab) (opens in a new tab)

In case a proof is not valid and error is thrown and the application will crash. In the future this should be handled more gracefully by showing an error message explaining the problem.

Storing verified proofs (opens in a new tab)

Referencing the proof

The proof is referenced in the AAD of a document snapshot.

First the client fetches the latest WorkspaceMemberDevicesProof from the server. (opens in a new tab)

Then the client creates a new document snapshot and references the WorkspaceMemberDevicesProof in the AAD. (opens in a new tab)

Using the proof

When the client receives a document snapshot it will try to get the data for that proof (first locally if available and then from the remote). (opens in a new tab)

Based on the proof a client can determine if the document snapshot and all referenced updates and ephemeral messages are signed by a an active device by a member of the workspace at the time of the workspace chain entry. (opens in a new tab)

Snapshot rotation

Whenever a new WorkspaceMemberDevicesProof is available the new document change must result in a snapshot. This is necessary since the new WorkspaceMemberDevicesProof might reference a new UserChain entry that added the current device of the user. Without referencing the new proof the client would sign the update with a device that is not referenced in the proof and therefore the update would be invalid. (opens in a new tab)