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.nio.ByteBuffer;
024import java.util.Optional;
025import java.util.UUID;
026
027import static java.util.Objects.requireNonNull;
028
029/** Engine-created proof of a committed credential enrollment for an app-approved account.
030 * This does not create an application session.
031 * @since 1.0.0 */
032@Immutable
033public final class WebAuthnRegistration {
034    private final @NonNull String credentialNamespace;
035    private final @NonNull String relyingPartyId;
036    private final byte @NonNull [] userHandle;
037    private final byte @NonNull [] credentialId;
038    private final @Nullable UUID aaguid;
039    private final boolean backupEligible;
040    private final boolean backedUp;
041    private final boolean userVerifiedAtRegistration;
042    WebAuthnRegistration(@NonNull String credentialNamespace, @NonNull String relyingPartyId,
043            byte @NonNull [] userHandle, byte @NonNull [] credentialId, byte @NonNull [] aaguid,
044            boolean backupEligible, boolean backedUp, boolean userVerifiedAtRegistration) {
045        this.credentialNamespace = requireNonNull(credentialNamespace);
046        this.relyingPartyId = requireNonNull(relyingPartyId);
047        this.userHandle = requireNonNull(userHandle).clone();
048        this.credentialId = requireNonNull(credentialId).clone();
049        if (requireNonNull(aaguid).length != 16 || (backedUp && !backupEligible))
050            throw new IllegalArgumentException("Invalid WebAuthn registration metadata");
051        ByteBuffer identifier = ByteBuffer.wrap(aaguid);
052        long most = identifier.getLong();
053        long least = identifier.getLong();
054        this.aaguid = most == 0 && least == 0 ? null : new UUID(most, least);
055        this.backupEligible = backupEligible;
056        this.backedUp = backedUp;
057        this.userVerifiedAtRegistration = userVerifiedAtRegistration;
058    }
059    /** Returns the configured namespace.
060     * @return namespace
061     * @since 1.0.0 */
062    public @NonNull String getCredentialNamespace() { return this.credentialNamespace; }
063    /** Returns the configured RP ID.
064     * @return relying-party ID
065     * @since 1.0.0 */
066    public @NonNull String getRelyingPartyId() { return this.relyingPartyId; }
067    /** Returns the authoritative account handle.
068     * @return defensive handle copy
069     * @since 1.0.0 */
070    public byte @NonNull [] getUserHandle() { return this.userHandle.clone(); }
071    /** Returns the newly registered credential ID.
072     * @return defensive ID copy
073     * @since 1.0.0 */
074    public byte @NonNull [] getCredentialId() { return this.credentialId.clone(); }
075    /** Returns the display-only authenticator model identifier when the client supplied a nonzero value.
076     * Under none attestation this value is not authenticated and must not drive authorization or policy.
077     * @return authenticator model identifier, or empty for the zero AAGUID
078     * @since 1.0.0 */
079    public @NonNull Optional<@NonNull UUID> getAaguid() { return Optional.ofNullable(this.aaguid); }
080    /** Returns whether the credential is eligible for backup.
081     * @return backup eligibility
082     * @since 1.0.0 */
083    public @NonNull Boolean isBackupEligible() { return Boolean.valueOf(this.backupEligible); }
084    /** Returns whether the credential was backed up when registered.
085     * @return backup state at registration
086     * @since 1.0.0 */
087    public @NonNull Boolean isBackedUp() { return Boolean.valueOf(this.backedUp); }
088    /** Returns whether user verification was observed when this credential was registered.
089     * This release requires user verification for every registration, so the value is always {@code true}.
090     * @return registration user-verification fact
091     * @since 1.0.0 */
092    public @NonNull Boolean isUserVerifiedAtRegistration() {
093        return Boolean.valueOf(this.userVerifiedAtRegistration);
094    }
095    /** Redacts account and credential identifiers.
096     * @return a fixed description
097     * @since 1.0.0 */
098    @Override public @NonNull String toString() { return "WebAuthnRegistration{identity=<redacted>}"; }
099}