Creates this account's first cross-signing identity.
This is the one destructive call on this surface, and it is destructive
exactly when it is wrong. An identity created over one the account
already has replaces it, and replacing it resets the trust of every device
and every person who ever verified the old one. There is no undo, and
nothing afterwards can detect it.
It is a separate call because that damage used to be reachable from
bootstrapCrossSigning, which this library tells you to call on
every launch. See that function for the measured race that made an honest
homeserver enough to do it.
What you must hold before calling this
The library's own precondition is that this process has asked the server
and the answer said the account has no identity. That is necessary and
it is not sufficient, and it is the whole reason this call is separate.
A /keys/query answer is only ever true of the instant the server sent
it. Between that instant and this call, another device of the same account
can publish an identity, and no answer already in hand can say so. So you
have to supply the fact the library cannot: that this account is meant
to be getting its first identity now. Your product knows things this
library does not, and any of them is a better basis than the answer alone:
the user has just created the account; this is the sign-up flow rather
than a relaunch; GET /_matrix/client/v3/devices lists no other session;
a person was asked and said yes.
Calling this on every launch, or as the automatic handler for
'identity_not_known', puts the decision back where it was and the race
back with it. If you do only one thing differently from
bootstrapCrossSigning, make it that.
The window is not closed, and the confirming query does not close it
The batch this queues carries a 'keys_query' for your own account after
the publication, so your ordinary send-and-report loop asks the server
once more straight afterwards.
Read what that is worth precisely, because it was overstated once and
the overstatement was measured. It covers the branch where the
publication did not land: the answer then carries the identity the
account really has, the keys that disagree with it are dropped, and
getIdentityStatus reports the truth instead of a device that holds
an identity the account does not have and asks the server nothing further.
It does not cover the branch where the publication did land, and that is
the branch that does the damage. If you sent the publication, answered
the authentication challenge and reported the 200, the overwrite is
complete: the confirming answer then comes back carrying your identity,
it matches your store, and this library reports a completely healthy
device. Nothing in the status, in any error, or in any later answer says
the identity that was there before was replaced. There is no path back and
this library will not pretend to offer one.
So the confirming query is worth having and is not a safety net. The thing
that keeps you out of this branch is the decision above.
The order the batch must be sent in, the user-interactive authentication
loop on 'signing_keys_upload', the rule about reporting only what a 2xx
returned, and the refusals 'account_keys_not_fetched' and
'identity_already_exists' all apply here unchanged and are documented
there rather than twice. 'identity_already_exists' is returned here
whether or not this device holds the private keys, because neither case
wants this call: holding them, it is bootstrapCrossSigning; not holding
them, it is requestSelfVerification.
Creates this account's first cross-signing identity.
This is the one destructive call on this surface, and it is destructive exactly when it is wrong. An identity created over one the account already has replaces it, and replacing it resets the trust of every device and every person who ever verified the old one. There is no undo, and nothing afterwards can detect it.
It is a separate call because that damage used to be reachable from bootstrapCrossSigning, which this library tells you to call on every launch. See that function for the measured race that made an honest homeserver enough to do it.
What you must hold before calling this
The library's own precondition is that this process has asked the server and the answer said the account has no identity. That is necessary and it is not sufficient, and it is the whole reason this call is separate.
A
/keys/queryanswer is only ever true of the instant the server sent it. Between that instant and this call, another device of the same account can publish an identity, and no answer already in hand can say so. So you have to supply the fact the library cannot: that this account is meant to be getting its first identity now. Your product knows things this library does not, and any of them is a better basis than the answer alone: the user has just created the account; this is the sign-up flow rather than a relaunch;GET /_matrix/client/v3/deviceslists no other session; a person was asked and said yes.Calling this on every launch, or as the automatic handler for
'identity_not_known', puts the decision back where it was and the race back with it. If you do only one thing differently frombootstrapCrossSigning, make it that.The window is not closed, and the confirming query does not close it
The batch this queues carries a
'keys_query'for your own account after the publication, so your ordinary send-and-report loop asks the server once more straight afterwards.Read what that is worth precisely, because it was overstated once and the overstatement was measured. It covers the branch where the publication did not land: the answer then carries the identity the account really has, the keys that disagree with it are dropped, and getIdentityStatus reports the truth instead of a device that holds an identity the account does not have and asks the server nothing further.
It does not cover the branch where the publication did land, and that is the branch that does the damage. If you sent the publication, answered the authentication challenge and reported the
200, the overwrite is complete: the confirming answer then comes back carrying your identity, it matches your store, and this library reports a completely healthy device. Nothing in the status, in any error, or in any later answer says the identity that was there before was replaced. There is no path back and this library will not pretend to offer one.So the confirming query is worth having and is not a safety net. The thing that keeps you out of this branch is the decision above.
Everything else is bootstrapCrossSigning's
The order the batch must be sent in, the user-interactive authentication loop on
'signing_keys_upload', the rule about reporting only what a 2xx returned, and the refusals'account_keys_not_fetched'and'identity_already_exists'all apply here unchanged and are documented there rather than twice.'identity_already_exists'is returned here whether or not this device holds the private keys, because neither case wants this call: holding them, it isbootstrapCrossSigning; not holding them, it is requestSelfVerification.