fix(jdbi): make username uniqueness case-insensitive to match DynamoDB

[wolpert]

Closes finding 5 of the full-project security audit.

The problem

DynamoDbUserLookup keys identity on USERNAME#<lower(username)>, so Admin and admin are one account on that backend. JdbiUserLookup matched exactly against V5's plain UNIQUE constraint, so on Postgres they were two.

Same library, same SPI, two identity models. A host that assumed the DynamoDB semantics — or moved between backends — could end up with look-alike accounts.

The fix

Flyway V12 adds a unique index on lower(username); the lookup queries fold case to match. getOrCreateHandle's ON CONFLICT now infers that expression index, so a racing insert of any case variant resolves to the existing row instead of minting a second handle.

The stored username keeps its original casing — only uniqueness and lookup fold — mirroring DynamoDB's UserItem, which stores the supplied form and lower-cases only the key. Display values round-trip unchanged.

PkAuthJdbiSchema.CURRENT_SCHEMA_VERSION → 12.

⚠️ Upgrade note: the migration can refuse to run

V12 runs a pre-flight check and refuses to migrate, naming the conflicting groups, if the database already holds usernames differing only by case:

pk-auth V12 cannot make username uniqueness case-insensitive: 1 existing username(s)
differ only by case. Conflicting groups: admin -> [ADMIN, Admin, admin]. Resolve these
first — decide which row is authoritative, migrate or delete the credentials belonging
to the others (credentials.user_handle references users.user_handle), then re-run.

Which of Admin and admin is authoritative, and what becomes of the other's credentials, is a business decision. A schema change shouldn't make it silently — nor should the operator meet it as an opaque duplicate-key error from the index build.

Testing

The guard only executes on a dirty database, which is exactly the code that would otherwise ship untested. V12UsernameCaseMigrationGuardIntegrationTest drives it on real Postgres (its own container, migrated to V11 then seeded):

• seeded conflicts → refused, all three variants named, and no index created so a re-run can succeed
• clean data → migrates, and the index then rejects a case variant
• the documented remediation (drop the loser, re-run) → succeeds

Plus case-insensitivity coverage on JdbiUserLookup itself. ./gradlew :pk-auth-persistence-jdbi:check passes (Docker required).

Also refreshes the DESIGN.md schema paragraph, which had drifted to "10".

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud