security: resolve MED-severity review findings (TODO #18-#33, #35-#36)

WebAuthn / core
- #18 finishAuthentication now binds the asserted credential to the
  challenge-record userHandle and to the response.userHandle when present;
  mismatches reject as UnknownCredential before WebAuthn4J verification.
- #33 Extract ChallengeValidator + sealed ChallengeValidation from the
  586-line DefaultPasskeyAuthenticationService; ceremony methods now follow
  validate -> verify -> map -> emit and the validator is unit-tested in
  isolation.

OTP / alt-flows
- #19 Mask phone numbers (+1***1234) in OtpService logs; drop message/body
  from LoggingSmsSender and LoggingEmailSender.
- #21 OtpRepository.incrementAttempts now returns the new count; OtpService
  rejects when the post-increment count exceeds maxAttempts, closing the
  TOCTOU window.
- #28 Replace Argon2id with HMAC-SHA256+server-side-pepper for OTP code
  storage (proportionate to 10^6 search space) and drop the argon2 dep
  from the OTP module.
- #20 sendLoginEmail collapses UserNotFound into Sent to remove the
  account-enumeration shape/timing side channel.
- #22 InMemoryRateLimiter now logs an INFO warning at construction and
  Javadocs the per-replica multiplier; production deployments must swap
  in a shared limiter.

JWT
- #24 Add RevocationCheck SPI (default no-op) consulted by
  PkAuthJwtValidator after signature/claims checks; new Revoked variant
  on JwtVerificationResult.

Persistence
- #25 JdbiUserLookup.createOrGetUserHandle is now a single atomic
  INSERT ... ON CONFLICT DO UPDATE ... RETURNING, removing the
  re-SELECT race window.
- #26 DynamoDB CredentialItem gains @DynamoDbVersionAttribute; updateLabel
  and updateSignCount retry up to 3 times on ConditionalCheckFailed.
- #27 New Flyway V6 migration adds revoked_at / revoked_reason to
  backup_codes + credentials and creates pkauth_audit_events. Backup-code
  consume and credential delete are now soft-deletes with audit rows;
  active-row queries filter on revoked_at IS NULL.

Adapters / API
- #29 Micronaut ceremony + admin controllers annotated
  @ExecuteOn(TaskExecutors.BLOCKING); Javadoc clarifies the
  blocking-SPI design.
- #31 New PkAuthCeremonyJwt.mintForAssertion helper shared by all three
  adapters; standardizes amr=["pkauth","webauthn"] and eliminates the
  Spring re-fetch.
- #35 Rename adapter classes to the PkAuth* prefix
  (Dropwizard Passkey*, Micronaut PkAuthJwtFilter, Spring admin
  controllers / result mappers / JwtAuthenticationToken).
- #36 Delete the unused Spring PkAuthAuthenticationProvider +
  PreAuthenticatedJwtToken (filter writes SecurityContextHolder directly).
- #30 PkAuthHttpError parses JSON body on construction and exposes
  error/detail/outcome; new CeremonyResult discriminated union mirrors
  the Java sealed result hierarchies.
- #32 Delete examples/spring-boot-demo DemoConfiguration; relying-party
  config now lives under pkauth.relying-party.* in application.yml.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: wolpert

clients/passkeys-browser/src/http.ts

@@ -5,12 +5,36 @@ import type { ClientOptions } from "./types";
 export class PkAuthHttpError extends Error {
   readonly status: number;
   readonly body: string;
+  readonly data: Record<string, unknown> | undefined;
 
   constructor(status: number, body: string) {
     super(`HTTP ${status}: ${body}`);
     this.name = "PkAuthHttpError";
     this.status = status;
     this.body = body;
+    try {
+      const parsed = JSON.parse(body);
+      this.data = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+        ? (parsed as Record<string, unknown>)
+        : undefined;
+    } catch {
+      this.data = undefined;
+    }
+  }
+
+  /** The `error` field from the parsed response body, if present. */
+  get error(): string | undefined {
+    return typeof this.data?.["error"] === "string" ? (this.data["error"] as string) : undefined;
+  }
+
+  /** The `detail` field from the parsed response body, if present. */
+  get detail(): string | undefined {
+    return typeof this.data?.["detail"] === "string" ? (this.data["detail"] as string) : undefined;
+  }
+
+  /** The `outcome` field from the parsed response body, if present. */
+  get outcome(): string | undefined {
+    return typeof this.data?.["outcome"] === "string" ? (this.data["outcome"] as string) : undefined;
   }
 }
 

clients/passkeys-browser/src/index.ts

@@ -2,6 +2,8 @@
 
 export * as base64url from "./base64url";
 export { PkAuthHttpError } from "./http";
+export type { CeremonyResult } from "./results";
+export { isCeremonySuccess, isCeremonyFailure } from "./results";
 export {
   PkAuthCeremonyClient,
   decodeCreationOptions,

clients/passkeys-browser/src/results.ts

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: MIT
+
+/**
+ * Discriminated union mirroring the Java sealed result hierarchies
+ * (AuthenticationResult / RegistrationResult) as returned by the pk-auth HTTP adapters.
+ *
+ * Authentication outcomes: success | challenge_invalid | origin_mismatch |
+ *   signature_invalid | unknown_credential | failed
+ *
+ * Registration outcomes: success | challenge_invalid | origin_mismatch |
+ *   attestation_rejected | duplicate_credential | invalid_payload | failed
+ */
+export type CeremonyResult =
+  | { outcome: 'success'; token: string; credentialId?: string }
+  | { outcome: 'challenge_invalid'; detail?: string }
+  | { outcome: 'origin_mismatch'; detail?: string }
+  | { outcome: 'signature_invalid'; detail?: string }
+  | { outcome: 'unknown_credential'; detail?: string }
+  | { outcome: 'attestation_rejected'; detail?: string }
+  | { outcome: 'duplicate_credential'; detail?: string }
+  | { outcome: 'invalid_payload'; detail?: string }
+  | { outcome: 'failed'; detail?: string };
+
+/** Type guard: narrows a CeremonyResult to the success variant. */
+export function isCeremonySuccess(
+  result: CeremonyResult,
+): result is { outcome: 'success'; token: string; credentialId?: string } {
+  return result.outcome === 'success';
+}
+
+/** Type guard: narrows a CeremonyResult to any failure variant. */
+export function isCeremonyFailure(
+  result: CeremonyResult,
+): result is Exclude<CeremonyResult, { outcome: 'success' }> {
+  return result.outcome !== 'success';
+}

clients/passkeys-browser/test/http.test.ts

@@ -97,4 +97,29 @@ describe("request()", () => {
     expect(e.message).toContain("500");
     expect(e.message).toContain("boom");
   });
+
+  it("PkAuthHttpError parses JSON body and exposes error/detail/outcome getters", () => {
+    const body = JSON.stringify({ error: "invalid_token", detail: "expired", outcome: "failed" });
+    const e = new PkAuthHttpError(400, body);
+    expect(e.data).toMatchObject({ error: "invalid_token", detail: "expired", outcome: "failed" });
+    expect(e.error).toBe("invalid_token");
+    expect(e.detail).toBe("expired");
+    expect(e.outcome).toBe("failed");
+    // raw body still preserved
+    expect(e.body).toBe(body);
+    expect(e.status).toBe(400);
+  });
+
+  it("PkAuthHttpError leaves data/error/detail/outcome undefined for non-JSON body", () => {
+    const e = new PkAuthHttpError(503, "Service Unavailable");
+    expect(e.data).toBeUndefined();
+    expect(e.error).toBeUndefined();
+    expect(e.detail).toBeUndefined();
+    expect(e.outcome).toBeUndefined();
+  });
+
+  it("PkAuthHttpError leaves data undefined when JSON body is not an object", () => {
+    const e = new PkAuthHttpError(400, JSON.stringify([1, 2, 3]));
+    expect(e.data).toBeUndefined();
+  });
 });

examples/dropwizard-demo/src/main/java/com/codeheadsystems/pkauth/demo/dropwizard/DemoApplication.java

@@ -114,8 +114,11 @@ private AdminService buildAdminService(DemoPersistence persistence) {
             persistence.userLookup(),
             clock,
             "http://localhost:8080");
+    byte[] otpPepper = new byte[32];
+    new java.security.SecureRandom().nextBytes(otpPepper);
     OtpService otp =
-        new OtpService(persistence.bindings().otpRepository(), new LoggingSmsSender(), clock);
+        new OtpService(
+            persistence.bindings().otpRepository(), new LoggingSmsSender(), clock, otpPepper);
     return DefaultAdminService.builder()
         .credentialRepository(persistence.bindings().credentialRepository())
         .userLookup(persistence.userLookup())

examples/spring-boot-demo/src/main/java/com/codeheadsystems/pkauth/examples/spring/DemoConfiguration.java

@@ -5,19 +5,17 @@
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 
 /**
- * Runnable entry point for the pk-auth Spring Boot demo. The auto-configuration in pk-auth-spring-
- * boot-starter wires every ceremony and admin endpoint; this class only provides the {@code
- * main(String[])} and a profile-conditional override for the {@code RelyingPartyConfig} (see {@link
- * DemoConfiguration}). To run:
+ * Runnable entry point for the pk-auth Spring Boot demo. The auto-configuration in
+ * pk-auth-spring-boot-starter wires every ceremony and admin endpoint; relying-party identity is
+ * configured via {@code pkauth.relying-party.*} in {@code application.yml} — no custom
+ * {@code @Bean @Primary RelyingPartyConfig} override is needed. To run:
  *
  * <pre>
- *   ./gradlew :examples:spring-boot-demo:bootRun           # JDBI persistence (Postgres if local)
- *   ./gradlew :examples:spring-boot-demo:bootRun \
- *       --args="--persistence=dynamodb"                    # DynamoDB persistence
+ *   ./gradlew :examples:spring-boot-demo:bootRun
  * </pre>
  *
- * <p>Without an explicit {@code --persistence=} flag the demo ships with the testkit's in-memory
- * SPIs (the autoconfigure defaults), so reviewers can boot the demo with no external services.
+ * <p>The demo ships with the testkit's in-memory SPIs ({@code pkauth.dev-mode=true}), so reviewers
+ * can boot the demo with no external services.
  */
 @SpringBootApplication
 public class SpringBootDemoApplication {

examples/spring-boot-demo/src/main/java/com/codeheadsystems/pkauth/examples/spring/SpringBootDemoApplication.java

@@ -6,15 +6,6 @@ spring:
   threads:
     virtual:
       enabled: true   # brief §11 — virtual threads in every adapter's HTTP server
-demo:
-  rp-id: localhost
-  rp-name: pk-auth Spring Boot demo
-  origins:
-    - http://localhost:8080
-  # `memory` (default) uses the testkit's InMemory SPIs — boots with no external services.
-  # `jdbi` requires a running Postgres + flyway-migrated schema (see docker-compose.yml).
-  # `dynamodb` requires a running DynamoDB Local + bootstrapped tables.
-  persistence: memory
 pkauth:
   # Demo runs against the testkit's in-memory SPIs by default. In production, do NOT set
   # `dev-mode: true` — supply real CredentialRepository / UserLookup / ChallengeStore /

examples/spring-boot-demo/src/main/resources/application.yml

@@ -1,9 +1,3 @@
-demo:
-  rp-id: example.com
-  rp-name: pk-auth Spring Boot demo (test)
-  origins:
-    - https://example.com
-  persistence: memory
 pkauth:
   dev-mode: true
   relying-party:

examples/spring-boot-demo/src/test/resources/application.yml

@@ -58,6 +58,8 @@ void setUp() {
     alice = users.register("alice", "Alice");
 
     Argon2 argon2 = Argon2Factory.create(Argon2Factory.Argon2Types.ARGON2id);
+    byte[] otpPepper = new byte[32];
+    new SecureRandom().nextBytes(otpPepper);
     backupCodeService =
         new BackupCodeService(backupCodes, CLOCK, new SecureRandom(), argon2, 1, 1024, 1, 5);
     otpService =
@@ -66,7 +68,7 @@ void setUp() {
             new LoggingSmsSender(),
             CLOCK,
             new SecureRandom(),
-            argon2,
+            otpPepper,
             Duration.ofMinutes(5),
             3,
             3,