fix(webauthn): address PR #287 review feedback

- Fix import ordering (alphabetical: jakarta < java < lombok < org) in
  WebAuthnCredential.java and WebAuthnCredentialColumnMappingTest.java
- Add Javadoc rationale to byte[] fields explaining Length.LONG32 is
  intentional to prevent future reversion to smaller lengths
- Add MIGRATION.md note for existing deployments with VARBINARY columns

Author: devondragon

MIGRATION.md

@@ -359,6 +359,32 @@ The `/user/updateUser` endpoint now uses `UserProfileUpdateDto`.
 
 ---
 
+**Issue: `user_credentials` table not created on MariaDB/MySQL (WebAuthn)**
+
+With `ddl-auto: update` or `create`, Hibernate previously mapped the `attestationObject` and
+`attestationClientDataJson` columns to `VARBINARY(65535)`. Two such columns exceed MariaDB's
+InnoDB 65,535-byte row-size limit, causing silent table creation failure. Symptoms include 500
+errors on `/user/auth-methods` or `/user/webauthn/credentials`.
+
+**Solution (upgrading from a version prior to this fix):**
+
+If the `user_credentials` table was never created, it will be created automatically on next
+startup with `ddl-auto: update` once you upgrade to this version.
+
+If the table exists with `VARBINARY` columns (created on a non-MariaDB database), run:
+
+```sql
+ALTER TABLE user_credentials
+    MODIFY COLUMN public_key              LONGBLOB NOT NULL,
+    MODIFY COLUMN attestation_object      LONGBLOB,
+    MODIFY COLUMN attestation_client_data_json LONGBLOB;
+```
+
+With `ddl-auto: update`, Hibernate will handle this automatically on MariaDB/MySQL. On
+PostgreSQL no schema change is needed — the columns map to `bytea` in both old and new versions.
+
+---
+
 **Issue: Java version incompatibility**
 
 Spring Boot 4.0 requires Java 21.

src/main/java/com/digitalsanctuary/spring/user/persistence/model/WebAuthnCredential.java

@@ -1,15 +1,15 @@
 package com.digitalsanctuary.spring.user.persistence.model;
 
-import java.time.Instant;
-import org.hibernate.Length;
 import jakarta.persistence.Column;
 import jakarta.persistence.Entity;
 import jakarta.persistence.FetchType;
 import jakarta.persistence.Id;
 import jakarta.persistence.JoinColumn;
 import jakarta.persistence.ManyToOne;
 import jakarta.persistence.Table;
+import java.time.Instant;
 import lombok.Data;
+import org.hibernate.Length;
 
 /**
  * JPA entity for the {@code user_credentials} table. Stores WebAuthn credentials (public keys) for passkey
@@ -30,7 +30,15 @@ public class WebAuthnCredential {
 	@JoinColumn(name = "user_entity_user_id", nullable = false)
 	private WebAuthnUserEntity userEntity;
 
-	/** COSE-encoded public key (typically 77-300 bytes, RSA keys can be larger). */
+	/**
+	 * COSE-encoded public key (typically 77-300 bytes, RSA keys can be larger).
+	 *
+	 * <p>{@code length = Length.LONG32} is intentional: it forces Hibernate to emit {@code LONGBLOB} on
+	 * MariaDB/MySQL (stored off-page, avoiding the 65,535-byte InnoDB row-size limit) while mapping to
+	 * {@code bytea} on PostgreSQL. Do not reduce this to a smaller value — doing so reintroduces the
+	 * MariaDB DDL failure described in GitHub issue #286. Do not replace with {@code @Lob}, which maps
+	 * to {@code OID} on PostgreSQL.</p>
+	 */
 	@Column(name = "public_key", nullable = false, length = Length.LONG32)
 	private byte[] publicKey;
 
@@ -58,11 +66,19 @@ public class WebAuthnCredential {
 	@Column(name = "backup_state", nullable = false)
 	private boolean backupState;
 
-	/** Attestation data from registration (can be several KB). */
+	/**
+	 * Attestation data from registration (can be several KB).
+	 *
+	 * <p>See {@link #publicKey} for why {@code length = Length.LONG32} is used here.</p>
+	 */
 	@Column(name = "attestation_object", length = Length.LONG32)
 	private byte[] attestationObject;
 
-	/** Client data JSON from registration (can be several KB). */
+	/**
+	 * Client data JSON from registration (can be several KB).
+	 *
+	 * <p>See {@link #publicKey} for why {@code length = Length.LONG32} is used here.</p>
+	 */
 	@Column(name = "attestation_client_data_json", length = Length.LONG32)
 	private byte[] attestationClientDataJson;
 

src/test/java/com/digitalsanctuary/spring/user/persistence/model/WebAuthnCredentialColumnMappingTest.java

@@ -1,8 +1,8 @@
 package com.digitalsanctuary.spring.user.persistence.model;
 
 import static org.assertj.core.api.Assertions.assertThat;
-import java.lang.reflect.Field;
 import jakarta.persistence.Column;
+import java.lang.reflect.Field;
 import org.hibernate.Length;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.params.ParameterizedTest;