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.totp;
018
019import java.util.Objects;
020import org.jspecify.annotations.NonNull;
021
022/**
023 * Opaque permanent record with an authenticated address and non-reused version. No TTL is allowed.
024 * This carrier validates framing only; the authenticator establishes authenticity before use.
025 * @since 1.0.0
026 */
027@javax.annotation.concurrent.Immutable
028public final class TotpStoreRecord {
029 private final @NonNull TotpStoreKey key;
030 private final @NonNull String version;
031 private final byte @NonNull [] sealedBytes;
032 private TotpStoreRecord(@NonNull TotpStoreKey key, @NonNull String version, byte @NonNull [] sealedBytes) {
033  this.key = Objects.requireNonNull(key);
034  TotpStoreKey.validateDigest(version);
035  if (sealedBytes.length == 0 || sealedBytes.length > 65536)
036   throw new IllegalArgumentException("Invalid sealed TOTP record length");
037  this.version = version;
038  this.sealedBytes = sealedBytes.clone();
039 }
040 /**
041  * Rehydrates an opaque bounded record, without granting protocol authority.
042  * @param key the exact address
043  * @param version the canonical unpadded base64url encoding of a fresh random 256-bit version
044  * @param sealedBytes the sealed payload, from 1 to 65536 bytes
045  * @return the immutable record
046  * @since 1.0.0
047  */
048 public static @NonNull TotpStoreRecord fromStoredForm(@NonNull TotpStoreKey key,
049   @NonNull String version, byte @NonNull [] sealedBytes) {
050  return new TotpStoreRecord(key, version, sealedBytes);
051 }
052 /**
053  * Returns the exact record address.
054  * @return the address
055  * @since 1.0.0
056  */
057 public @NonNull TotpStoreKey getKey() { return this.key; }
058 /**
059  * Returns the exact version to preserve and compare atomically.
060  * @return the opaque non-reused version
061  * @since 1.0.0
062  */
063 public @NonNull String getVersion() { return this.version; }
064 /**
065  * Returns a defensive copy of the sealed payload.
066  * @return the sealed record
067  * @since 1.0.0
068  */
069 public byte @NonNull [] getSealedBytes() { return this.sealedBytes.clone(); }
070 /**
071  * Redacts address, version and payload.
072  * @since 1.0.0
073  */
074 @Override public @NonNull String toString() { return "TotpStoreRecord{record=<redacted>}"; }
075}