Every device this library has been told about for userId, and the trust
it currently reports for each, sorted by device id.
This is the only place a completed verification becomes visible, by
either method. A device that has been through
requestVerification to confirmVerification, with both
sides agreeing, reads 'verified' here where it read 'unverified'
before; so does one that went through getVerificationCode and
confirmScan, or submitScannedCode, with nobody comparing
a string at all. This paragraph named only the first pair, which is the
"verification is a short string" claim on the call the README itself
calls the only place a verification is visible.
It is also where a scanned verification becomes visible, and it is
the only place the change itself is: a flow finished by a scan emits no
trust_changed down onCryptoSignal, only a
verification_completed that names the flow and carries no trust, so
this call is what a product reads when it gets one. See that function's
own doc for why the two are not one signal.
Nothing else in this library changes as a result of a verification -- in
particular a decrypted event's sender does not become authenticated,
because that path consults cross-signing and a verification of either
kind sets local trust. See TrustState.
'verified' no longer means a person compared a string with this device
Read it as "trusted", and read nothing more into it. This call maps
from one boolean underneath, which is "locally trusted OR signed by an
identity we have verified". The second half of that had no way to be true
until this library could hold a signing identity of its own. It can, from
bootstrapCrossSigning, and the consequence is immediate and
deliberate: verifying one device of a user moves every device of that
user to 'verified' at once, including devices that appear afterwards,
with nobody comparing anything on any of them.
That is correct rather than a defect. It is the entire point of
cross-signing: you verify a person once instead of once per device they
own. But it is a behaviour change a caller cannot see coming, so it is
said here rather than left to be discovered. Anything that read this
value as "a human compared a string with this exact device" was right
before this release and is wrong from it. If that is the question your
product is really asking, this call has never been the one to ask, and it
is now further from it than it was: what an individual event can be said
to prove is EventEnvelope.senderVerification, which is a different
question with a different and more expensive answer.
'recognized' stays folded into 'verified', deliberately
TrustState declares a third value for exactly the state the
paragraph above creates -- a device believed because its owner's identity
signed it, with no person having compared anything -- and this call does
not produce it. That is a decision taken in this release rather than an
absence left over from an earlier one, and the reasoning is at
TrustState so a product reading the union meets it there too.
An empty array does not mean the user has no devices. It means this
library has been told about none of them. Devices arrive through the
outbound pump: receiveSyncChanges flags a user as changed, that
produces a 'keys_query' request among takeOutgoingRequests'
output, and only markRequestSent on that request puts anything in
the store. A caller that has never done that gets [] for a user with a
dozen devices, and gets it successfully. There is no way for this library
to tell the two apart, because it sends nothing itself.
Your own device always reads 'verified', and always has. This
library marks it locally trusted the moment it creates the machine,
because this process holds its private keys and there is nothing left to
prove. That is correct, and it is a trap for anything reading this list:
"some device here reads verified" is true of an installation that has
never run a verification in its life. What carries a claim is a device of
another user changing from 'unverified' to 'verified'.
After verifying another person by code, pump once more
A code verification with somebody else produces one thing: a signature
your account makes over their identity. Whether they read 'verified'
here depends on that signature being in your store, and making it does
not put it there. Only the homeserver's answer to a 'keys_query' about
them does.
This library queues that query for you, on the sync that completes the
flow, so there is no extra call to find. But queued is not answered: the
request comes out of takeOutgoingRequests like any other, and this
value does not move until you have sent it and reported it with
markRequestSent. So when onCryptoSignal announces
'verification_completed' for a flow with another person, drain the
pump once more before reading this, and expect 'unverified' if you
read it in between. Verifying one of your own devices needs none of
that: it reads 'verified' the moment the flow finishes.
Every device this library has been told about for
userId, and the trust it currently reports for each, sorted by device id.This is the only place a completed verification becomes visible, by either method. A device that has been through requestVerification to confirmVerification, with both sides agreeing, reads
'verified'here where it read'unverified'before; so does one that went through getVerificationCode and confirmScan, or submitScannedCode, with nobody comparing a string at all. This paragraph named only the first pair, which is the "verification is a short string" claim on the call the README itself calls the only place a verification is visible.It is also where a scanned verification becomes visible, and it is the only place the change itself is: a flow finished by a scan emits no
trust_changeddown onCryptoSignal, only averification_completedthat names the flow and carries no trust, so this call is what a product reads when it gets one. See that function's own doc for why the two are not one signal.Nothing else in this library changes as a result of a verification -- in particular a decrypted event's sender does not become authenticated, because that path consults cross-signing and a verification of either kind sets local trust. See TrustState.
'verified'no longer means a person compared a string with this deviceRead it as "trusted", and read nothing more into it. This call maps from one boolean underneath, which is "locally trusted OR signed by an identity we have verified". The second half of that had no way to be true until this library could hold a signing identity of its own. It can, from bootstrapCrossSigning, and the consequence is immediate and deliberate: verifying one device of a user moves every device of that user to
'verified'at once, including devices that appear afterwards, with nobody comparing anything on any of them.That is correct rather than a defect. It is the entire point of cross-signing: you verify a person once instead of once per device they own. But it is a behaviour change a caller cannot see coming, so it is said here rather than left to be discovered. Anything that read this value as "a human compared a string with this exact device" was right before this release and is wrong from it. If that is the question your product is really asking, this call has never been the one to ask, and it is now further from it than it was: what an individual event can be said to prove is EventEnvelope.senderVerification, which is a different question with a different and more expensive answer.
'recognized'stays folded into'verified', deliberatelyTrustState declares a third value for exactly the state the paragraph above creates -- a device believed because its owner's identity signed it, with no person having compared anything -- and this call does not produce it. That is a decision taken in this release rather than an absence left over from an earlier one, and the reasoning is at TrustState so a product reading the union meets it there too.
An empty array does not mean the user has no devices. It means this library has been told about none of them. Devices arrive through the outbound pump: receiveSyncChanges flags a user as changed, that produces a
'keys_query'request among takeOutgoingRequests' output, and only markRequestSent on that request puts anything in the store. A caller that has never done that gets[]for a user with a dozen devices, and gets it successfully. There is no way for this library to tell the two apart, because it sends nothing itself.Your own device always reads
'verified', and always has. This library marks it locally trusted the moment it creates the machine, because this process holds its private keys and there is nothing left to prove. That is correct, and it is a trap for anything reading this list: "some device here reads verified" is true of an installation that has never run a verification in its life. What carries a claim is a device of another user changing from'unverified'to'verified'.After verifying another person by code, pump once more
A code verification with somebody else produces one thing: a signature your account makes over their identity. Whether they read
'verified'here depends on that signature being in your store, and making it does not put it there. Only the homeserver's answer to a'keys_query'about them does.This library queues that query for you, on the sync that completes the flow, so there is no extra call to find. But queued is not answered: the request comes out of takeOutgoingRequests like any other, and this value does not move until you have sent it and reported it with markRequestSent. So when
onCryptoSignalannounces'verification_completed'for a flow with another person, drain the pump once more before reading this, and expect'unverified'if you read it in between. Verifying one of your own devices needs none of that: it reads'verified'the moment the flow finishes.