Hands in the payload your scanner read off the other device's screen.
The obligation this call puts on a product, and it is the sharp one
payload must be the raw bytes the code carried, not a decoded
string. React Native's popular scanners -- vision camera's code scanner,
expo's barcode handler -- surface a decoded value: string, and that
string cannot carry this payload: it is binary, it is not valid text, and
a string round trip replaces every byte that could not be represented.
Reach for the raw byte output your scanner offers, and if it offers none,
that scanner cannot be used for this.
This library cannot undo that damage; what it can do is name it. A payload
that went through a string arrives as 'scanned_code_malformed', which is
the one signal a product gets that its scanner is the problem rather than
the person holding the phone.
This is one call and two protocol steps. The scan is registered and
the message that tells the other side the code was read is queued for the
pump. Drain it: a scan nobody hears about leaves both sides waiting.
Refusals, and why there are four of them
A product must be able to say four different things here, so four
different kinds arrive:
'scanned_code_unrecognised' -- not one of these codes at all. Point
the camera at the code the other device is showing.
'scanned_code_malformed' -- the bytes did not survive. Scan again, and
check that your scanner yields bytes rather than text.
'scanned_code_for_another_flow' -- a real code, for a different
verification. Nothing is wrong; the wrong screen was read.
'scanned_code_refused' -- a code for this flow carrying keys that are
not the ones this side holds for the device on the other end. The only
one of the four that can mean something is wrong rather than that
somebody aimed badly. Refuse and start again from a fresh request;
scanning the same code again cannot help, because the keys it carries
will not have changed.
It means that and nothing else. A peer device this side has no record of
is a different answer, 'unknown_device', precisely because the remedy is
the opposite: drain takeOutgoingRequests, report the key query it
hands you, and scan the very same code again.
Scanning also needs a signing identity on both sides, so
'identity_not_known' and 'peer_identity_not_known' are reachable here
too, and name which side is missing one. It can also reject with
'unknown_flow', for an identifier naming no flow this process is taking
part in, and with 'wrong_stage', for a flow that is not one a code can be
scanned into or is already over.
Scanning is not verifying. When this resolves, nothing is verified
yet: the other side has still to confirm, and messages have to cross.
Pump, and watch getVerificationStage: it reads 'confirmed' from
here, meaning this side has done everything asked of it, and 'done' once
the other side has finished. It never reads 'code-scanned' on this side,
because that stage belongs to whoever held up a screen.
Hands in the payload your scanner read off the other device's screen.
The obligation this call puts on a product, and it is the sharp one
payloadmust be the raw bytes the code carried, not a decoded string. React Native's popular scanners -- vision camera's code scanner, expo's barcode handler -- surface a decodedvalue: string, and that string cannot carry this payload: it is binary, it is not valid text, and a string round trip replaces every byte that could not be represented. Reach for the raw byte output your scanner offers, and if it offers none, that scanner cannot be used for this.This library cannot undo that damage; what it can do is name it. A payload that went through a string arrives as
'scanned_code_malformed', which is the one signal a product gets that its scanner is the problem rather than the person holding the phone.This is one call and two protocol steps. The scan is registered and the message that tells the other side the code was read is queued for the pump. Drain it: a scan nobody hears about leaves both sides waiting.
Refusals, and why there are four of them
A product must be able to say four different things here, so four different kinds arrive:
'scanned_code_unrecognised'-- not one of these codes at all. Point the camera at the code the other device is showing.'scanned_code_malformed'-- the bytes did not survive. Scan again, and check that your scanner yields bytes rather than text.'scanned_code_for_another_flow'-- a real code, for a different verification. Nothing is wrong; the wrong screen was read.'scanned_code_refused'-- a code for this flow carrying keys that are not the ones this side holds for the device on the other end. The only one of the four that can mean something is wrong rather than that somebody aimed badly. Refuse and start again from a fresh request; scanning the same code again cannot help, because the keys it carries will not have changed.It means that and nothing else. A peer device this side has no record of is a different answer,
'unknown_device', precisely because the remedy is the opposite: drain takeOutgoingRequests, report the key query it hands you, and scan the very same code again.Scanning also needs a signing identity on both sides, so
'identity_not_known'and'peer_identity_not_known'are reachable here too, and name which side is missing one. It can also reject with'unknown_flow', for an identifier naming no flow this process is taking part in, and with'wrong_stage', for a flow that is not one a code can be scanned into or is already over.Scanning is not verifying. When this resolves, nothing is verified yet: the other side has still to confirm, and messages have to cross. Pump, and watch getVerificationStage: it reads
'confirmed'from here, meaning this side has done everything asked of it, and'done'once the other side has finished. It never reads'code-scanned'on this side, because that stage belongs to whoever held up a screen.