Summary of change

Modifications to Support Android Native WebAuthn Origins

Context

Currently, when attempting to define an Android Native origin (in the formatandroid:apk-key-hash:<base64Url-string-without-padding-of-fingerprint>) throughsupertokens_python.recipe.webauthn.register_options andsupertokens_python.recipe.webauthn.sign_in_options, the Core returns anINVALID_OPTIONS_ERROR status without specifying a reason. The "origin" field of these functions appears to only work with HTTP(S) URLs.

There is no indication of this limitation in any of the documentation I've reviewed, which leads me to believe this has never been tested under these conditions (i.e., from an AndroidNative application, without an Pre-Built UI (frontend SDK), as is possible withreact-native-passkey).

I initially attempted to useFunction overrides, a solution I'm not particularly fond of. While this can work during the "Register Options" phase (where it's possible to switch the Android Native origin to the HTTPS URL provided as the origin when calling the Python function to bypass the Core), it becomes impossible during the Sign-In phase, as this invalidates the signature sent by the device, causing the Core to legitimately reject the request.

Therefore, I propose this PR with several modifications to allow the Core to support this origin format in the same way it handles HTTP(S) URLs, avoiding these workarounds (which don't work anyway).

This is my first pull request to an open source project of this scale, and I'm open to any feedback if I'm on the wrong track or doing things incorrectly.

Modified Files

1. OptionsValidator.java

File:src/main/java/io/supertokens/webauthn/validator/OptionsValidator.java

Changelog:

• Added detection for Android origins starting withandroid:apk-key-hash:
• Strict validation of the URL-safe base64 hash:
  • Verification that the hash is not empty
  • Validation of URL-safe base64 format (allowed characters: A-Z, a-z, 0-9, -, _)
  • Verification of exact length: 43 characters (base64 of SHA-256 fingerprint, 32 bytes)
• HTTP(S) origins continue to work normally

2. Utils.java (Tests)

File:src/test/java/io/supertokens/test/webauthn/Utils.java

Modifications:

• Added overloads forregisterOptions() andsignInOptions() accepting anorigin parameter
• Allows easy testing with different types of origins

3. TestAndroidOriginValidation.java (New File)

File:src/test/java/io/supertokens/test/webauthn/api/TestAndroidOriginValidation.java

Tests Added:

1. testValidAndroidOrigin() : Verifies that a valid Android origin is accepted
2. testValidAndroidOriginWithAlternativeHash() : Tests with an alternative valid hash
3. testAndroidOriginWithEmptyHash() : Verifies rejection of an empty hash
4. testAndroidOriginWithInvalidCharacters() : Verifies rejection of invalid characters
5. testAndroidOriginWithInvalidLength() : Verifies rejection of incorrect length (must be exactly 43 characters)
6. testAndroidOriginForSignInOptions() : Tests Android origins for sign-in
7. testMixedOriginsSupport() : Verifies that HTTP, HTTPS, and Android coexist

Test Execution

I executed this test to validate proper functionality:

From thesupertokens-root:

./gradlew :supertokens-core:test --tests"io.supertokens.test.webauthn.api.TestAndroidOriginValidation"

Origin Examples

Valid Android Origins

android:apk-key-hash:47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFUandroid:apk-key-hash:sYUC8p5I9SxqFernBPHmDxz_YVZXmVJdW8s-m3RTTqEandroid:apk-key-hash:AbCdEfGhIjKlMnOpQrStUvWxYz0123456789-_AbCd

Invalid Android Origins

android:apk-key-hash:                                  # Empty hashandroid:apk-key-hash:invalid@hash#with$special!        # Invalid characters (not URL-safe base64)android:apk-key-hash:abc                               # Incorrect length (must be 43 characters)android:apk-key-hash:Lir5oIjf552K/XN4bTul0VS2aiE=      # Incorrect length and contains invalid characters (+/ and =)

HTTP(S) Origins (Still Supported)

http://example.comhttps://example.comhttps://subdomain.example.com

WebAuthn Specification Compliance

These modifications comply with the WebAuthn specification, which defines different origin formats depending on the platform:

• Web and iOS:https://example.com,http://localhost, andhttps://<RPID> (in accordance withApple App Site Association (AASA))
• Android:android:apk-key-hash:<base64Url-string-without-padding-of-fingerprint> (seehttps://developer.android.com/identity/passkeys/create-passkeys#verify)

Security Notes

• The URL-safe base64 hash (43 characters) represents the SHA-256 fingerprint of the Android application's signing certificate
• This validation ensures that only legitimate Android applications with the correct certificate can use WebAuthn
• Android origins are not validated against therelyingPartyId in the same way as HTTP(S) origins (compliant with the spec)
• The hash format follows the WebAuthn specification for Android native applications

Test Plan

Command used to test the implementation:

gradletest --tests"io.supertokens.test.webauthn.api.TestAndroidOriginValidation"

Documentation changes

I don't feel it's necessary to make changes to the documentation, as there was nothing to suggest the current limitation. This should be transparent to the few people in this situation.

Checklist for important updates

• Changelog has been updated
  • If there are any db schema changes, mention those changes clearly
• coreDriverInterfaceSupported.json file has been updated (if needed)
• pluginInterfaceSupported.json file has been updated (if needed)
• Changes to the version if needed
  • Inbuild.gradle
• If added a new paid feature, edit thegetPaidFeatureStats function in FeatureFlag.java file
• Had installed and ran the pre-commit hook
• If there are new dependencies that have been added inbuild.gradle, please make sure to add them
  inimplementationDependencies.json.
• Update functiongetValidFields inio/supertokens/config/CoreConfig.java if new aliases were added for any core
  config (similar to theaccess_token_signing_key_update_interval config alias).
• Issue this PR against the latest non released version branch.
  • To know which one it is, run find the latest released tag (git tag) in the formatvX.Y.Z, and then find the
    latest branch (git branch --all) whoseX.Y is greater than the latest released tag.
  • If no such branch exists, then create one from the latest released branch.
• If added a foreign key constraint onapp_id_to_user_id table, make sure to delete from this table when deleting
  the user as well ifdeleteUserIdMappingToo is false.
• If added a new recipe, then make sure to update the bulk import API to include the new recipe.