001/* 002 * Copyright 2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.revetsec.webauthn; 018 019import org.jspecify.annotations.NonNull; 020import org.jspecify.annotations.Nullable; 021 022import javax.annotation.concurrent.Immutable; 023import java.util.Optional; 024 025import static java.util.Objects.requireNonNull; 026 027/** Engine-created proof of a committed, stored-key WebAuthn authentication. The application 028 * still decides whether to create a session or authorize a sensitive action. 029 * @since 1.0.0 */ 030@Immutable 031public final class WebAuthnAuthentication { 032 private final @NonNull String credentialNamespace; 033 private final @NonNull String relyingPartyId; 034 private final byte @NonNull [] userHandle; 035 private final byte @NonNull [] credentialId; 036 private final boolean backupEligible; 037 private final boolean backedUp; 038 private final @NonNull Kind kind; 039 private final @Nullable String actionPurpose; 040 WebAuthnAuthentication(@NonNull String credentialNamespace, @NonNull String relyingPartyId, 041 byte @NonNull [] userHandle, byte @NonNull [] credentialId, 042 boolean backupEligible, boolean backedUp, @NonNull Kind kind, 043 @Nullable String actionPurpose) { 044 this.credentialNamespace = requireNonNull(credentialNamespace); 045 this.relyingPartyId = requireNonNull(relyingPartyId); 046 this.userHandle = requireNonNull(userHandle).clone(); 047 this.credentialId = requireNonNull(credentialId).clone(); 048 if (backedUp && !backupEligible) 049 throw new IllegalArgumentException("Invalid WebAuthn backup state"); 050 this.backupEligible = backupEligible; 051 this.backedUp = backedUp; 052 this.kind = requireNonNull(kind); 053 this.actionPurpose = actionPurpose; 054 } 055 /** Returns the configured namespace. 056 * @return namespace 057 * @since 1.0.0 */ 058 public @NonNull String getCredentialNamespace() { return this.credentialNamespace; } 059 /** Returns the configured RP ID. 060 * @return relying-party ID 061 * @since 1.0.0 */ 062 public @NonNull String getRelyingPartyId() { return this.relyingPartyId; } 063 /** Returns the authoritative account handle. 064 * @return defensive handle copy 065 * @since 1.0.0 */ 066 public byte @NonNull [] getUserHandle() { return this.userHandle.clone(); } 067 /** Returns the verified credential ID. 068 * @return defensive ID copy 069 * @since 1.0.0 */ 070 public byte @NonNull [] getCredentialId() { return this.credentialId.clone(); } 071 /** Returns the credential's permanent backup eligibility. 072 * @return backup eligibility 073 * @since 1.0.0 */ 074 public @NonNull Boolean isBackupEligible() { return Boolean.valueOf(this.backupEligible); } 075 /** Returns the backup state stored by this successful authentication. 076 * @return current backed-up state 077 * @since 1.0.0 */ 078 public @NonNull Boolean isBackedUp() { return Boolean.valueOf(this.backedUp); } 079 /** Returns whether this proof satisfied discoverable sign-in or account-pinned reauthentication. 080 * @return ceremony kind 081 * @since 1.0.0 */ 082 public @NonNull Kind getKind() { return this.kind; } 083 /** Returns the action bound to an account-pinned reauthentication, when present. 084 * @return action purpose 085 * @since 1.0.0 */ 086 public @NonNull Optional<@NonNull String> getActionPurpose() { 087 return Optional.ofNullable(this.actionPurpose); 088 } 089 /** Redacts the account, credential and action. 090 * @return a fixed description 091 * @since 1.0.0 */ 092 @Override public @NonNull String toString() { return "WebAuthnAuthentication{identity=<redacted>}"; } 093 094 /** The two authentication ceremonies. 095 * @since 1.0.0 */ 096 @Immutable public enum Kind { 097 /** Discoverable sign-in. */ SIGN_IN, 098 /** Account-pinned sensitive action. */ REAUTHENTICATION 099 } 100}