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}