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 java.util.Set;
021import org.jspecify.annotations.NonNull;
022
023/**
024 * The exact immutable scope and sealing configuration requesting recovery admission.
025 * Core constructs this context from its actual operation configuration.
026 * @since 1.0.0
027 */
028@javax.annotation.concurrent.Immutable
029public final class TotpRecoveryContext {
030 private final @NonNull String credentialNamespace;
031 private final @NonNull String recoveryEpoch;
032 private final @NonNull String activeSealingKeyId;
033 private final @NonNull Set<@NonNull String> openingSealingKeyIds;
034 private final TotpRecoveryContext.@NonNull Purpose purpose;
035 private TotpRecoveryContext(@NonNull String namespace, @NonNull String epoch,
036   @NonNull String activeKeyId, @NonNull Set<@NonNull String> openingKeyIds,
037   TotpRecoveryContext.@NonNull Purpose purpose) {
038  TotpStoreKey.validateScope(namespace); TotpStoreKey.validateScope(epoch);
039  this.credentialNamespace = namespace; this.recoveryEpoch = epoch;
040  this.activeSealingKeyId = Objects.requireNonNull(activeKeyId);
041  this.openingSealingKeyIds = Set.copyOf(openingKeyIds);
042  if (activeKeyId.isEmpty() || !this.openingSealingKeyIds.contains(activeKeyId)
043    || this.openingSealingKeyIds.size() > 17)
044   throw new IllegalArgumentException("Invalid TOTP sealing configuration");
045  this.purpose = Objects.requireNonNull(purpose);
046 }
047 static @NonNull TotpRecoveryContext fromConfiguration(@NonNull String credentialNamespace,
048   @NonNull String recoveryEpoch, @NonNull String activeSealingKeyId,
049   @NonNull Set<@NonNull String> openingSealingKeyIds, TotpRecoveryContext.@NonNull Purpose purpose) {
050  return new TotpRecoveryContext(credentialNamespace, recoveryEpoch, activeSealingKeyId,
051    openingSealingKeyIds, purpose);
052 }
053 /**
054  * Returns the configured credential namespace.
055  * @return the namespace
056  * @since 1.0.0
057  */
058 public @NonNull String getCredentialNamespace() { return this.credentialNamespace; }
059 /**
060  * Returns the externally controlled recovery epoch.
061  * @return the epoch
062  * @since 1.0.0
063  */
064 public @NonNull String getRecoveryEpoch() { return this.recoveryEpoch; }
065 /**
066  * Returns the key ID actually used for new records.
067  * @return the active sealing key ID
068  * @since 1.0.0
069  */
070 public @NonNull String getActiveSealingKeyId() { return this.activeSealingKeyId; }
071 /**
072  * Returns the immutable active and retained opening key IDs.
073  * @return every configured opening key ID, including the active key
074  * @since 1.0.0
075  */
076 public @NonNull Set<@NonNull String> getOpeningSealingKeyIds() { return this.openingSealingKeyIds; }
077 /**
078  * Returns the requested admission purpose.
079  * @return initialization or ordinary operation
080  * @since 1.0.0
081  */
082 public TotpRecoveryContext.@NonNull Purpose getPurpose() { return this.purpose; }
083 /**
084  * Redacts the scope and key configuration.
085  * @since 1.0.0
086  */
087 @Override public @NonNull String toString() { return "TotpRecoveryContext{configuration=<redacted>}"; }
088 /**
089  * The explicitly authorized recovery admission purpose.
090  * @since 1.0.0
091  */
092 @javax.annotation.concurrent.Immutable
093 public enum Purpose {
094  /**
095   * Provision only a fresh externally authorized epoch.
096   */ INITIALIZE_NAMESPACE,
097  /**
098   * Authenticate or manage an initialized epoch.
099   */ OPERATION
100 }
101}