Fix passkey logins failing on iOS Safari due to binary user handles

Merged
AL
10d ago
+129-11

Fixes #41

getPasskeyUserHandle() returns raw binary HMAC bytes as the WebAuthn user.id. The sample handle in the report decodes to bytes full of EF BF BD (U+FFFD) — binary data that went through a lossy UTF-8 decode/encode, where bytes below 0x80 survive and everything else is replaced. iOS Safari does that to the user handle somewhere between registration and the assertion, so the returned handle can never match the stored one again and CheckUserHandle throws an unhandled InvalidUserHandleException, which surfaces as a 500.

Two changes:

  • getPasskeyUserHandle() now returns the hex form of the same HMAC (dropped binary: true). 64 ASCII characters, still within WebAuthn's 64 byte limit for user.id, and it survives any UTF-8 round trip.
  • VerifyPasskey catches InvalidUserHandleException and rethrows it as an InvalidPasskeyException. Credentials that already registered a binary handle from an affected device are unrecoverable server-side — the authenticator holds the corrupted user.id — so those logins now fail with a 422 telling the user to re-register instead of a 500.

The derivation change does not affect existing credentials: verification compares the assertion against the handle stored on the credential record, never a recomputed one (the same reason the existing secret-rotation test passes). New tests cover a legacy credential with a raw binary handle still verifying when the authenticator returns it intact, and a regression test that corrupts the handle the same way iOS does (UTF-8 decode with U+FFFD substitution) and asserts the login now fails with the validation error.

One side effect worth noting: a user who registers an additional passkey after this change gets a hex handle on the new credential while older credentials keep their binary one. Each credential is validated against its own stored handle, so both keep working.

composer test (Pint, PHPStan, Pest — 79 tests, 182 assertions) passes on PHP 8.5.