Evaluate Account Linking interface

[bgins]

We are evaluating the Webnative account linking interface and seeking feedback from developers.

Existing interface

Account linking in Webnative creates event emitters that listen for account linking events.

An accountProducer listens for a PIN from an accountConsumer and delegates the account when a user verifies the PINs match on both devices.

// The producer should already have an active session
const producer = await program.auth.accountProducer(program.session.username)

// The producer receives a challenge PIN from the consumer
producer.on("challenge", challenge => {
  // Either show `challenge.pin` or have the user input a PIN and check if they're equal.
  if (userInput === challenge.pin) challenge.confirmPin()
  else challenge.rejectPin()
})

// The producer reports whether a user approved or rejected
producer.on("link", ({ approved }) => {
  if (approved) console.log("Linked device successfully")
})

The accountConsumer listens for similar events:

// The consumer should not have an active session
const consumer = await program.auth.accountConsumer(username)

// The consumer generates a PIN and sends it to the producer
consumer.on("challenge", ({ pin }) => {
  // Display the PIN
  showPinOnUI(pin)
})

// The consumer receives an approval or rejection message from the producer
consumer.on("link", async ({ approved, username }) => {
  if (approved) {
    console.log(`Successfully authenticated as ${username}`)
    session = await program.auth.session()
  }
})

Alternative interface

An alternative interface could move the account linking to program.accountLinking and change the way it works.

A device with an existing session calls program.accountLinking.listen and listens for a PIN from a device that would like to be linked. It delegates the account when a user verifies the PINs match on both devices.

// On a device with an active session
program.accountLinking.listen()

// This device receives a PIN from the device that would like to be linked
program.accountLinking.on("challenge", (pin) => {
  // Either show `challenge.pin` or have the user input a PIN and check if they're equal.
  if (userInput === pin) program.accountLinking.confirmPin()
})

// Report whether the user approved or rejected
program.accountLinking.on("link", ({ approved }) => {
  if (approved) console.log("Linked device successfully")
})

A device that would like to be linked calls program.accountLinking.link and listens for similar messages.

// On a device without a session
program.accountLinking.link(username)

// This device generates a PIN and sends it to the device with an active session
program.accountLinking.on("challenge", (pin) => {
  // Display the PIN
  showPinInUI(pin)
})

// Handle an approval or rejection message from the device with an active session
program.accountLinking.on("link", ({ approved, username }) => {
  if (approved) {
    console.log(`Successfully authenticated as ${username}`)
    session = await program.auth.session()
  }
})

[nichoth]

👍 I like this potential change because the method names seem a little more semantically accurate. I'm not thinking to myself "what is a consumer vs producer".

[bgins]

Agreed that the names are not the clearest. We chose the names to match the existing AWAKE spec at the time we implemented the existing interface: https://whitepaper.fission.codes/accounts/login/awake

The names don't really make much sense without that context though. 💯

[vorcigernix]

Agree with @nichoth

[bgins]

A few notes on how these interfaces compare in my mind.

Managed interface

The alternative interface is more managed than the existing interface. Instead of creating an event emitter, one already exists on the program and you listen on it or request a link from it. One advantage to the managed interface is that it prevents you from accidentally creating more than one producer or consumer, which can result in unexpected behavior.

Producer or consumer events?

The existing interface is more explicit than the alternative interface. When you receive an event, you know for sure whether it is a producer or consumer event. With the alternative interface, you rely on the context of whether an active session exists or not.

In theory, this should be fine. You can guard by checking for a session, and the session should only change after linking has completed and you call program.auth.session. (Are there edge cases that I missing here?)

Stop/Cancel linking

One thing we haven't outlined here is how to stop or cancel linking. In the existing interface, both the producer and consumer can cancel during linking by calling consumer.cancel for example. The producer will continue to listen for more consumers until it is cancelled (which really is more like "stop listening"). How would we handle cancelling and stopping with the alternative interface?

[icidasset]

I think stopping/cancelling the link with the alternative interface would be the inverse of the listen and link methods. So for example, stopListening and cancelLink respectively.