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 com.revetsec.internal.encoding.Base64Url; 020import com.revetsec.internal.encoding.EncodingException; 021import java.nio.charset.StandardCharsets; 022import java.security.MessageDigest; 023import java.security.NoSuchAlgorithmException; 024import java.util.Base64; 025import java.util.Arrays; 026import org.jspecify.annotations.NonNull; 027import org.jspecify.annotations.Nullable; 028 029/** 030 * Typed, namespace-bound authoritative address. Binary identifiers are represented only by 031 * canonical SHA-256 digests in the stored address. Constructing a key confers no protocol authority. 032 * The storage form is sensitive and must not be logged. 033 * @since 1.0.0 034 */ 035@javax.annotation.concurrent.Immutable 036public final class WebAuthnStoreKey { 037 private static final Base64.Encoder ENCODER = Base64.getUrlEncoder().withoutPadding(); 038 private static final int MAXIMUM_STORED_FORM_LENGTH = 583; 039 private final @NonNull String storageKey; 040 private final WebAuthnStoreKey.@NonNull Kind kind; 041 042 private WebAuthnStoreKey(@NonNull String storageKey, WebAuthnStoreKey.@NonNull Kind kind) { 043 this.storageKey = storageKey; 044 this.kind = kind; 045 } 046 047 private WebAuthnStoreKey(@NonNull String namespace, @NonNull String relyingPartyId, 048 WebAuthnStoreKey.@NonNull Kind kind, byte @NonNull [] identifier) { 049 validateNamespace(namespace); 050 validateRelyingPartyId(relyingPartyId); 051 this.kind = kind; 052 this.storageKey = "wa1:" + encode(namespace.getBytes(StandardCharsets.US_ASCII)) + ':' 053 + encode(relyingPartyId.getBytes(StandardCharsets.US_ASCII)) + ':' + kind.name() + ':' 054 + encode(sha256(identifier)); 055 } 056 057 /** Address for a 32-byte random ceremony ID. 058 * @param namespace the credential namespace 059 * @param relyingPartyId the canonical RP ID 060 * @param ceremonyId the decoded random ceremony ID 061 * @return the typed address 062 * @since 1.0.0 */ 063 public static @NonNull WebAuthnStoreKey forCeremony(@NonNull String namespace, 064 @NonNull String relyingPartyId, byte @NonNull [] ceremonyId) { 065 if (ceremonyId.length != 32) throw new IllegalArgumentException("Invalid ceremony ID"); 066 return new WebAuthnStoreKey(namespace, relyingPartyId, Kind.CEREMONY, ceremonyId); 067 } 068 069 /** Address for a credential ID of 1–1023 bytes. 070 * @param namespace the credential namespace 071 * @param relyingPartyId the canonical RP ID 072 * @param credentialId the browser credential ID 073 * @return the typed address 074 * @since 1.0.0 */ 075 public static @NonNull WebAuthnStoreKey forCredential(@NonNull String namespace, 076 @NonNull String relyingPartyId, byte @NonNull [] credentialId) { 077 validateUserIdentifier(credentialId, 1023); 078 return new WebAuthnStoreKey(namespace, relyingPartyId, Kind.CREDENTIAL, credentialId); 079 } 080 081 /** Address for the credential index of a 1–64-byte account handle. 082 * @param namespace the credential namespace 083 * @param relyingPartyId the canonical RP ID 084 * @param userHandle the opaque account handle 085 * @return the typed address 086 * @since 1.0.0 */ 087 public static @NonNull WebAuthnStoreKey forAccountCredentialIndex(@NonNull String namespace, 088 @NonNull String relyingPartyId, byte @NonNull [] userHandle) { 089 validateUserIdentifier(userHandle, 64); 090 return new WebAuthnStoreKey(namespace, relyingPartyId, Kind.ACCOUNT_CREDENTIAL_INDEX, userHandle); 091 } 092 093 /** Address for the active state and revocation fence of a 1–64-byte account handle. 094 * @param namespace the credential namespace 095 * @param relyingPartyId the canonical RP ID 096 * @param userHandle the opaque account handle 097 * @return the typed address 098 * @since 1.0.0 */ 099 public static @NonNull WebAuthnStoreKey forAccountFence(@NonNull String namespace, 100 @NonNull String relyingPartyId, byte @NonNull [] userHandle) { 101 validateUserIdentifier(userHandle, 64); 102 return new WebAuthnStoreKey(namespace, relyingPartyId, Kind.ACCOUNT_FENCE, userHandle); 103 } 104 105 /** Address for the authenticated immutable authority/minimum root of a namespace and RP. 106 * @param namespace the credential namespace 107 * @param relyingPartyId the canonical RP ID 108 * @return the namespace clock address 109 * @since 1.0.0 */ 110 public static @NonNull WebAuthnStoreKey forNamespaceClock(@NonNull String namespace, 111 @NonNull String relyingPartyId) { 112 return new WebAuthnStoreKey(namespace, relyingPartyId, Kind.NAMESPACE_CLOCK, new byte[0]); 113 } 114 115 /** Reconstructs an exact canonical persistence address, bounded to 583 ASCII characters. 116 * This supports application-owned inventory and reseal of revoked credentials whose raw IDs 117 * are no longer listed. It checks address syntax only: it does not authenticate a record, 118 * approve a namespace, authorize maintenance, or construct a verification proof. The relying 119 * party still checks scope and permanent-record eligibility before reseal; ceremony addresses 120 * can round-trip but cannot be resealed. Treat the input and returned address as sensitive. 121 * @param storageKey the exact address from a trusted persistence inventory 122 * @return the reconstructed typed address without rehashing its identifier digest 123 * @throws NullPointerException if storageKey is null 124 * @throws IllegalArgumentException if the address is not canonical or exceeds its bounds 125 * @since 1.0.0 */ 126 public static @NonNull WebAuthnStoreKey fromStoredForm(@NonNull String storageKey) { 127 if (storageKey.length() > MAXIMUM_STORED_FORM_LENGTH) 128 throw new IllegalArgumentException("Invalid WebAuthn storage address"); 129 String[] parts = storageKey.split(":", -1); 130 if (parts.length != 5 || !parts[0].equals("wa1")) 131 throw new IllegalArgumentException("Invalid WebAuthn storage address"); 132 byte[] namespace = null, rp = null, digest = null; 133 try { 134 namespace = decodeStoredPart(parts[1], 128); 135 rp = decodeStoredPart(parts[2], 253); 136 digest = decodeStoredPart(parts[4], 32); 137 if (digest.length != 32) throw new IllegalArgumentException(); 138 for (byte value : namespace) if (value < 0x21 || value > 0x7e) throw new IllegalArgumentException(); 139 for (byte value : rp) if (value < 0x21 || value > 0x7e) throw new IllegalArgumentException(); 140 String ns = new String(namespace, StandardCharsets.US_ASCII); 141 String relyingParty = new String(rp, StandardCharsets.US_ASCII); 142 validateNamespace(ns); 143 validateRelyingPartyId(relyingParty); 144 Kind kind = Kind.valueOf(parts[3]); 145 if (kind == Kind.NAMESPACE_CLOCK 146 && !forNamespaceClock(ns, relyingParty).getStorageKey().equals(storageKey)) 147 throw new IllegalArgumentException(); 148 return new WebAuthnStoreKey(storageKey, kind); 149 } catch (IllegalArgumentException | EncodingException invalid) { 150 throw new IllegalArgumentException("Invalid WebAuthn storage address"); 151 } finally { 152 if (namespace != null) Arrays.fill(namespace, (byte) 0); 153 if (rp != null) Arrays.fill(rp, (byte) 0); 154 if (digest != null) Arrays.fill(digest, (byte) 0); 155 } 156 } 157 158 private static byte @NonNull [] decodeStoredPart(@NonNull String encoded, int maximum) 159 throws EncodingException { 160 if (encoded.isEmpty() || encoded.length() > (maximum * 4 + 2) / 3) 161 throw new IllegalArgumentException(); 162 return Base64Url.decode(encoded); 163 } 164 165 /** Returns the exact persistence address; do not log it. 166 * @return the storage address 167 * @since 1.0.0 */ 168 public @NonNull String getStorageKey() { return this.storageKey; } 169 170 /** Returns the key's record kind. 171 * @return the record kind 172 * @since 1.0.0 */ 173 public WebAuthnStoreKey.@NonNull Kind getKind() { return this.kind; } 174 175 /** Compares complete addresses. @since 1.0.0 */ 176 @Override public boolean equals(@Nullable Object other) { 177 return other instanceof WebAuthnStoreKey key && this.storageKey.equals(key.storageKey); 178 } 179 180 /** Returns the complete address hash. @since 1.0.0 */ 181 @Override public int hashCode() { return this.storageKey.hashCode(); } 182 183 /** Redacts the address. @since 1.0.0 */ 184 @Override public @NonNull String toString() { return "WebAuthnStoreKey{address=<redacted>}"; } 185 186 private static void validateUserIdentifier(byte @NonNull [] identifier, int maximum) { 187 if (identifier.length == 0 || identifier.length > maximum) 188 throw new IllegalArgumentException("Invalid identifier length"); 189 } 190 191 private static void validateNamespace(@NonNull String namespace) { 192 if (namespace.isEmpty() || namespace.length() > 128) throw new IllegalArgumentException("Invalid namespace"); 193 for (int i = 0; i < namespace.length(); i++) { 194 char character = namespace.charAt(i); 195 if (character < 0x21 || character > 0x7e) throw new IllegalArgumentException("Invalid namespace"); 196 } 197 } 198 199 private static void validateRelyingPartyId(@NonNull String relyingPartyId) { 200 if (relyingPartyId.length() < 3 || relyingPartyId.length() > 253) 201 throw new IllegalArgumentException("Invalid RP ID"); 202 String[] labels = relyingPartyId.split("\\.", -1); 203 if (labels.length < 2) throw new IllegalArgumentException("Invalid RP ID"); 204 for (String label : labels) { 205 if (label.isEmpty() || label.length() > 63 || label.charAt(0) == '-' 206 || label.charAt(label.length() - 1) == '-') throw new IllegalArgumentException("Invalid RP ID"); 207 for (int i = 0; i < label.length(); i++) { 208 char character = label.charAt(i); 209 if (!((character >= 'a' && character <= 'z') || (character >= '0' && character <= '9') 210 || character == '-')) throw new IllegalArgumentException("Invalid RP ID"); 211 } 212 } 213 boolean allDigits = true; 214 for (String label : labels) { 215 for (int i = 0; i < label.length(); i++) if (label.charAt(i) < '0' || label.charAt(i) > '9') allDigits = false; 216 } 217 if (allDigits) throw new IllegalArgumentException("Invalid RP ID"); 218 } 219 220 private static @NonNull String encode(byte @NonNull [] bytes) { return ENCODER.encodeToString(bytes); } 221 222 private static byte @NonNull [] sha256(byte @NonNull [] bytes) { 223 try { return MessageDigest.getInstance("SHA-256").digest(bytes); } 224 catch (NoSuchAlgorithmException exception) { throw new IllegalStateException("SHA-256 unavailable", exception); } 225 } 226 227 /** The five authoritative record kinds. 228 * @since 1.0.0 */ 229 @javax.annotation.concurrent.Immutable 230 public enum Kind { 231 /** Single-use ceremony or retained consumption proof. */ 232 CEREMONY, 233 /** Credential state keyed by its unique ID. */ 234 CREDENTIAL, 235 /** Per-account credential index. */ 236 ACCOUNT_CREDENTIAL_INDEX, 237 /** Per-account active state and revocation fence. */ 238 ACCOUNT_FENCE, 239 /** Per-namespace monotonic observed-time fence. */ 240 NAMESPACE_CLOCK 241 } 242}