generateAttestationOptions parameters structure

[mariusmarais]

I'm wondering what the reasoning is behind changing the parameters the generate methods take, as opposed to the "normal" structure of the DOM options objects.

Specifically:

const attestOptions = generateAttestationsOptions({
  rpName: 'XYZ Widgets',
  rpId: 'localhost',
  userID: 'xxxxx-aaaa-marius',
  userName: 'marius',
  userDisplayName: 'Marius Marais',
  ...
});

yields

{
  rp: {
    name: 'XYZ Widgets',
    id: 'localhost'
  },
  user: {
    id: 'xxxxx-aaaa-marius',
    name: 'marius',
    displayName: 'Marius Marais'
  }
  ...
}

I'm not sure this counts as simpler... I'm finding it more difficult to work through https://webauthn.guide/ with SimpleWebAuthn side-by-side, simply because the latter changes things for no good reason I can see.

It might feel easier to get going in some cases, but as soon as you really want to move forward, there's a constant cross-referencing, especially into the spec. Do you feel it's worth the difference?

(Updating the options should be simple enough, I see no reason not to maintain backwards compatibility.)

[MasterKale]

...because the latter changes things for no good reason I can see

Ah, but there was a reason - I spell it out on the Philosophy page of the docs: https://simplewebauthn.dev/docs/simplewebauthn/philosophy

SimpleWebAuthn attempts to offer a developer-friendly pair of libraries that simplify the above dance. @simplewebauthn/server exports a small number of methods requiring a handful of simple inputs that pair with the two primary methods exported by @simplewebauthn/browser. No converting back and forth between Uint8Array (or was this supposed to be an ArrayBuffer...?) and String, no worrying about JSON compatibility - SimpleWebAuthn takes care of it all!

That's really what my intention was in collapsing the arguments: I want to offer a library that a developer with no familiarity with the WebAuthn spec could reasonably implement with the assistance of some higher-level implementation docs paired with judicious JSDoc commenting like this to help communicate the various values:

Sure, as someone who is now deep into the spec it can be a little annoying to remember that the rpName argument maps to rp.name, but even with that I left subtle indicators in the names of the arguments that can help communicate which part of the options those values will get set to.

At the end of the day I think it's more important that this library makes implementation easy for developers with close to no knowledge about the WebAuthn spec. WebAuthn should be easy to set up so that devs can go on to work on more interesting features. As such I stand by the structure of the library and its arguments, though as evidenced in other discussions and past issues here I'm open to suggestions for improvement :)

[mariusmarais]

That's a good point, thanks for taking the time to explain your reasoning.

All the marshalling you mention in the docs quote is certainly very useful, and if the "cost" to me is the slightly mangled (in my opinion) options, it's still a good tradeoff. I'm just reminded of Apollo Server in the GraphQL world, where it's extremely easy to get going, but you end up having to redo a lot of stuff manually once you want to leave the rails.

I think this library is rapidly approaching best-in-class status, so keeping it simple and accessible to new devs is a noble goal. Please just also keep the advanced exits clear 😄