API compatibility with `navigator.credentials.get/create`

[kzlar]

Hi @peterferguson,

Appreciate the work on this plugin!

I'm using https://github.com/better-auth/better-auth/ (which uses https://github.com/MasterKale/SimpleWebAuthn under the hood) to facilitate passkey usage on my website, and wanted to add the same functionality to my expo app, and so I was very happy to find this repo 🥳

I'm still in the PoC phase so I tried the following setup:

import * as ReactNativePasskeys from 'react-native-passkeys'
// Pass SimpleWebAuthn checks
globalThis.PublicKeyCredential = () => {}
// Initialize global credentials API
navigator.credentials = {
  get: ReactNativePasskeys.get,
  create: ReactNativePasskeys.create
}

This succeeds in the basic task of letting my use existing better-auth/simplewebauthn code along with this plugin, however upon actually trying to create a passkey, the app crashes.
From what I can tell, the reason is that the API options don't exactly match up. I looked up the types and it's pretty clear:

export declare function create(request: Omit<PublicKeyCredentialCreationOptionsJSON, 'extensions'> & {
    extensions?: {
        largeBlob?: AuthenticationExtensionsLargeBlobInputs;
    };
} & Pick<CredentialCreationOptions, 'signal'>): Promise<RegistrationResponseJSON | null>;

It seems like this plugin "flattens" CredentialCreationOptions.publicKey.
Is there a particular reason for it? Are you open to amending the API to conform to the web standard?

P.S. the actual crash comes from

react-native-passkeys/ios/ReactNativePasskeysModule.swift

Line 151 in 16570e8

let crossPlatformCredentialProvider = ASAuthorizationSecurityKeyPublicKeyCredentialProvider(relyingPartyIdentifier: request.rp.id!)

but in general some argument validation is probably not a bad idea, if you'd be open to it I can try to add a PR to add it.

[kzlar]

I've been trying to work around this but I think I'm at an impasse. Seems like the web credentials.create expects buffers to be Uint8Array (see https://github.com/MasterKale/SimpleWebAuthn/blob/1f6216e1da94c56b5623e1ba0409664bb4e75295/packages/browser/src/methods/startRegistration.ts#L45C9-L45C13 and https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredentialCreationOptions#creating_a_public_key_credential) but it seems like the API of this plugin expects them to be a base64 url string?

If I understand correctly this is due to how js<->native api works, but then I'd still expect the user-facing api (eg create) to expect Uint8Array and have the js part of the plugin do the conversion (eg here

react-native-passkeys/src/index.ts

Line 32 in 16570e8

return await ReactNativePasskeysModule.create(request)

)

I hope you'd be open to change the API to be more compatible!

[kzlar]

Further along I also see that the returned credential does not have getClientExtensionResults (https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/getClientExtensionResults)

[kzlar]

Ok, getTransports is also missing from credential.response. I noticed that credential.response.transports is an empty array, is that expected?

I ended up getting create to work, here's what I have:

function bufferToBase64URLString(buffer: ArrayBuffer): string {
  const bytes = new Uint8Array(buffer)
  let str = ''

  for (const charCode of bytes) {
    str += String.fromCharCode(charCode)
  }

  const base64String = btoa(str)

  return base64String.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')
}

navigator.credentials = {
  // Note: get likely doesn't work as is
  get: ReactNativePasskeys.get,
  create: async (v: CredentialCreationOptions) => {
    type NativeCredentialCreationOptions = Parameters<
      typeof ReactNativePasskeys.create
    >[0]
    if (!v.publicKey?.rp || !v.publicKey?.challenge || !v.publicKey?.user) {
      throw new Error('Passkey Create: Invalid args')
    }
    const v2: NativeCredentialCreationOptions = {
      signal: v.signal,
      challenge: bufferToBase64URLString(v.publicKey.challenge),
      pubKeyCredParams: v.publicKey?.pubKeyCredParams ?? [],
      rp: v.publicKey.rp,
      user: {
        ...v.publicKey.user,
        id: bufferToBase64URLString(v.publicKey.user.id),
      },
      authenticatorSelection: v.publicKey?.authenticatorSelection,
      attestation: v.publicKey?.attestation,
      // extensions: v.publicKey?.extensions,
      timeout: v.publicKey?.timeout,
    }

    const credential = await ReactNativePasskeys.create(v2)
    if (credential) {
      return {
        ...credential,
        getClientExtensionResults: () => credential.clientExtensionResults,
        rawId: base64URLStringToBuffer(credential.rawId),
        response: {
          ...credential.response,
          getTransports: () => credential.response.transports ?? [],
          attestationObject: base64URLStringToBuffer(
            credential.response.attestationObject
          ),
          clientDataJSON: base64URLStringToBuffer(
            credential.response.clientDataJSON
          ),
        },
      }
    } else {
      return credential
    }
  },
}

While the above seems to be an acceptable workaround for now, my hope is that the api can be made compatible with the web versions :)

[peterferguson]

Hey, sorry for taking so long to get back to you!

You're right — the web standard should be followed as closely as possible in this library. I'll add the missing getTransport and getClientExtensionResults functions.

That said, I do think the shim part of your workaround should stay in userland, for example:

globalThis.PublicKeyCredential = () => {}

navigator.credentials = {
  get: ReactNativePasskeys.get,
  create: ReactNativePasskeys.create
}

Thanks again for the detailed issue and suggesting the change — I had missed those functions in the spec and haven't been staying fully on top of the updates! I'll get those functions added ASAP & close this issue when added 👍

[kzlar]

Hey, appreciate your response!

I agree the shims should stay in userland (although I'd recommend adding it as an example or to the README), but please note that it's beyond getTransport and getClientExtensionResults. It's also buffer conversions that need to happen to fully match the API.

I've been using this in production for a couple of days and here are the full conversion functions I'm using:

import * as ReactNativePasskeys from 'react-native-passkeys'
import { base64URLStringToBuffer, bufferToBase64URLString } from './utils'

type NativeCredentialCreationOptions = Parameters<
  typeof ReactNativePasskeys.create
>[0]
type NativeGetCreationOptions = Parameters<typeof ReactNativePasskeys.get>[0]
type NativeCredentialType = Exclude<
  Awaited<ReturnType<typeof ReactNativePasskeys.create>>,
  null
>

export function WebauthnCreateOptionsToRNPasskeyCreateOptions(
  opts: CredentialCreationOptions
) {
  if (
    !opts.publicKey?.rp ||
    !opts.publicKey?.challenge ||
    !opts.publicKey?.user
  ) {
    throw new Error('Passkey Create: Invalid args')
  }
  const optsForRNPasskey: NativeCredentialCreationOptions = {
    signal: opts.signal,
    challenge: bufferToBase64URLString(opts.publicKey.challenge),
    pubKeyCredParams: opts.publicKey?.pubKeyCredParams ?? [],
    rp: opts.publicKey.rp,
    user: {
      ...opts.publicKey.user,
      id: bufferToBase64URLString(opts.publicKey.user.id),
    },
    authenticatorSelection: opts.publicKey?.authenticatorSelection,
    attestation: opts.publicKey?.attestation,
    // extensions: opts.publicKey?.extensions, // Handle extensions if needed
    timeout: opts.publicKey?.timeout,
  }
  return optsForRNPasskey
}

export function RNPasskeyCredentialToWebauthnCredential(
  credential: NativeCredentialType
) {
  return {
    ...credential,
    id: credential.id, // Ensure id is present
    rawId: base64URLStringToBuffer(credential.rawId),
    type: 'public-key', // Standard type
    getClientExtensionResults: () => credential.clientExtensionResults ?? {},
    response: {
      ...credential.response,
      getTransports: () => credential.response.transports ?? ['internal'],
      attestationObject: credential.response.attestationObject
        ? base64URLStringToBuffer(credential.response.attestationObject)
        : null,
      authenticatorData: credential.response.authenticatorData
        ? base64URLStringToBuffer(credential.response.authenticatorData)
        : null,
      clientDataJSON: credential.response.clientDataJSON
        ? base64URLStringToBuffer(credential.response.clientDataJSON)
        : null,
      userHandle: credential.response.userHandle
        ? base64URLStringToBuffer(credential.response.userHandle)
        : null,
      signature: credential.response.signature
        ? base64URLStringToBuffer(credential.response.signature)
        : null,
    },
  } as unknown as PublicKeyCredential // Cast needed due to interface differences
}

export function WebauthnGetOptionsToRNPasskeyCreateOptions(
  opts: CredentialRequestOptions
) {
  if (!opts.publicKey?.rpId) {
    throw new Error('Passkey Create: Invalid args')
  }
  const optsForRNPasskey: NativeGetCreationOptions = {
    challenge: bufferToBase64URLString(opts.publicKey.challenge),
    // extensions: opts.publicKey?.extensions, // Handle extensions if needed
    rpId: opts.publicKey.rpId,
    userVerification: 'required',
    timeout: opts.publicKey?.timeout,
  }
  return optsForRNPasskey
}

So my 2c is something along those lines should be a part of the js part of this library, but I appreciate that this can be a non trivial api breakage.

I did also notice that credential.response.transports can be empty, which is why I default it to ['internal'], wondering if that's intentional or an issue on my end?

Anyway, hope this helps clarify, let me know if there's anything else I can help with on this. Thanks!

[peterferguson]

I did also notice that credential.response.transports can be empty, which is why I default it to ['internal'], wondering if that's intentional or an issue on my end?

I wouldn't default transports to ['internal']. That value specifically indicates a platform authenticator but this may not be the case. If the user agent (browser in the web case) is returning no transports—which is acceptable according to the spec—then you should also just return an empty array to indicate this.

It's also buffer conversions that need to happen to fully match the API.

On the lack of array buffers, I originally converted to base64url immediately to save the user a standard serialisation step, as it was common on RN to immediately take the result & pass it to the server.

I think this was the wrong approach & in v0.4.0 I will either:

• Take a configuration approach where the user inits a passkey class with configuration something like

import { Passkeys } from 'react-native-passkeys'

const passkeys = new Passkeys({ convertArrayBuffers: true })
// or 
const { create, get } = new Passkeys({ convertArrayBuffers: true })

/**
 * Maintaining backwards compatibility by simply initing the class as above & exporting it as default. 
 * 
 * i.e.
 * 
 * import * as passkeys from 'react-native-passkeys'
 * 
 * or 
 * 
 * import { create, get } from 'react-native-passkeys'
 * 
 * is still valid & operates as expected
 */

• Or attempt to have full web api compatibility (where I implement a toJSON method that does the conversion).
  This would entail support for the more static methods (Support getClientCapabilities static method #37, Support new static methods parseCreationOptionsFromJSON & parseRequestOptionsFromJSON #39 & Support isUserVerifyingPlatformAuthenticatorAvailable static method #40) & also overloads for { publicKey: ... } options api — originally not supported to simplify the api since only the publicKey option of credential api is supported in iOS & Android.

In my head the latter is probably the correct outlook for this library, however, the backwards compatibility story is more difficult here. I haven't landing on a path for this yet.

Let me know your thoughts 👍

ps. I know @cruzdanilo you keep up with the issues here too, so would love to hear your thoughts

[cruzdanilo]

hey @peterferguson, thanks for the ping!

i'd definitely vote for option 2 - aligning fully with the web api.

following web standards is just solid practice - brings consistency, leverages wider ecosystem knowledge, and makes things more future-proof. specifically here, it means less friction for devs coming from web, avoids folks needing custom wrappers/shims, and ensures this library automatically plays nicely with other js/ts libs expecting the standard navigator.credentials api.

breaking changes for v0.4 are fine imo, totally normal for a major (or 0.x) bump according to semver. the benefits of matching the web standard feel worth the migration cost.

cheers

[kzlar]

I wouldn't default transports to ['internal']. That value specifically indicates a platform authenticator but this may not be the case. If the user agent (browser in the web case) is returning no transports—which is acceptable according to the spec—then you should also just return an empty array to indicate this.

That makes sense, however I still don't understand why I got an empty transport array, is that something that comes from iOS directly or from this library?
From the docs, it seems like internal is the best fit for iOS since the authentication and keys are bound to the secure enclave.

In my head the latter is probably the correct outlook for this library, however, the backwards compatibility story is more difficult here. I haven't landing on a path for this yet.

Let me know your thoughts 👍

I guess both technically work, but IMO full web compatibility is more desirable. I definitely understand the backwards compatibility dilemma, but honestly since this library has yet to reach v1 maturity, I think breaking API is definitely within reason. Especially since the breakage is due to the aforementioned reason.