decouple http-protocol from lib API

[rbroggi]

Hello all,

After studying a bit the library I wonder whether we could evolve some of the library APIs from taking things like *http.Request as input to something that is more general and strongly typed. Some users of the library might be using different kinds of protocols (I'm one of those), and those users would be better served if presented with types that are descriptive about what the content of the methods like FinishLogin expect rather than a super generic (and implementation-dependant) *http.Request.

So I would suggest to go from:

FinishLogin(user User, session SessionData, response *http.Request) (*Credential, error)

to

FinishLogin(user User, session SessionData, response Assertion) (*Credential, error)

where

// Assertion packs an assertion made by a client-authenticator in
// response to a server-side generated challenge
type Assertion struct {
	// ID is the identifier for the credential that was used to generate the
	// authentication assertion. Specs:
	// https://w3c.github.io/webauthn/#ref-for-dom-credential-id
	ID string
	// RawID is the identifier again, but in binary form. Specs:
	// https://w3c.github.io/webauthn/#dom-publickeycredential-rawid
	RawID []byte
	// Type is the value of the object’s interface object's [[type]] slot,
	// which specifies the credential type represented by this object.
	// This should be type "public-key" for Webauthn credentials.
	Type string
	// AssertionResponse packs the assertion response by the authenticator
	AssertionResponse AssertionResponse
}

// AssertionResponse contains the raw authenticator assertion data
type AssertionResponse struct {
	// AuthenticatorData is another item used during authentication as source bytes
	// to generate the assertion signature. Specs:
	// https://w3c.github.io/webauthn/#authenticator-data
	AuthenticatorData []byte
	// ClientData is a collection of the data passed from the browser to the
	// authenticator. It is one of the items used during authentication as the source
	// bytes to generate the signature. specs:
	// https://w3c.github.io/webauthn/#dictdef-collectedclientdata
	ClientData []byte
	// Signature is the signature generated by the private key associated with this
	// credential. On the server, the public key will be used to verify that this
	// signature is valid. Specs:
	// https://w3c.github.io/webauthn/#dom-authenticatorassertionresponse-signature
	Signature []byte
	// UserHandle is optionally provided by the authenticator, and represents the
	// user.id that was supplied during registration. It can be used to relate this
	// assertion to the user on the server. It is encoded here as a UTF-8 byte array.
	// Specs:
	// https://w3c.github.io/webauthn/#dom-authenticatorassertionresponse-userhandle
	UserHandle []byte
}

Some of the benefits for this approach:

1. More informative API and method signature. Users understand right away all the fields necessary to use the method by only seeing the method signature.
2. Decouple from a specific transport protocol.

WDYT?

p.s.: where applicable we could change types from []byte to URLEncodedBase64

[james-d-elliott]

This just needs some documentation. There may be a way to simplify this, the second method is specifically what is necessary.

The method of achieving this is as follows:

	if response, err = protocol.ParseCredentialRequestResponseBody(bytes.NewReader(body)); err != nil {
		// handle err

		return
	}
	
	if credential, err = webauthn.ValidateLogin(user, session, response); err != nil {
		// handle err

		return
	}
	
	// handle success

Where ValidateLogin is a function with the following signature:

type ValidateLogin func(user User, session SessionData, parsedResponse *protocol.ParsedCredentialAssertionData) (*Credential, error)

[isgj]

I'm using GRPC and some fields are []byte . If I marshal the struct as json to a buffer those fields will have padding in the json representation. And this will fail the parsing from this lib. So I should map my struct to a similar one where []byte are URLEncodedBase64 first.
IMHO having the validation on a struct would make more sense. (SomeStruct.Validate : (*ParsedCredentialCreationData, error))
Thanks for the response.

[james-d-elliott]

Yep, okay that makes sense. We can add it similar to how you suggested relatively quickly.

[james-d-elliott]

Can we check #128 suits the use cases?

[rbroggi]

@isgj - I am also using gRPC, this was one of the reasons why I suggested to go towards a more protocol agnostic API.

[isgj]

using the branch from the PR, it works nice

ccr := &protocol.CredentialCreationResponse{
	PublicKeyCredential: protocol.PublicKeyCredential{
		Credential: protocol.Credential{
			ID:   in.Msg.Id,
			Type: in.Msg.Type,
		},
		RawID:                   in.Msg.RawId,
		AuthenticatorAttachment: in.Msg.AuthenticatorAttachment,
	},
	AttestationResponse: protocol.AuthenticatorAttestationResponse{
		AuthenticatorResponse: protocol.AuthenticatorResponse{
			ClientDataJSON: in.Msg.Response.ClientDataJSON,
		},
		AttestationObject: in.Msg.Response.AttestationObject,
		Transports:        in.Msg.Response.Transports,
	},
}
cred, err := ccr.Parse()