Class TotpAuthenticator

java.lang.Object
com.revetsec.totp.TotpAuthenticator

@ThreadSafe public final class TotpAuthenticator extends Object
Standalone TOTP enrollment, once-only verification and recovery codes. Applications own account authorization, primary authentication, sessions, CSRF, network admission, durable storage and recovery administration. TOTP is not phishing resistant. Configuration is immutable and building performs no storage, gate, cryptographic-provider or network work.

The fixed profile is HMAC-SHA1, six digits and 30-second Unix-epoch steps, accepting the previous, current or next step exactly once. Five failed or unsettled attempts per account in five minutes are shared by confirmation, TOTP and recovery codes. Six-digit confirmation and verification also share a durable limit of ten failed or unsettled attempts per rolling 24 hours. Recovery codes have 128 bits of entropy and remain subject to the five-minute shared limit, so they can provide fallback after that cooldown. Malformed submitted codes of at most 128 characters count as attempts; longer inputs are rejected before recovery admission or storage access. A successful attempt removes only its own reservations; earlier failed or unsettled attempts remain charged until their respective windows expire. A confirmed factor has ten random 128-bit recovery codes from separate draws. Pending enrollment lasts five minutes; starting replacement leaves the old factor active until confirmation commits.

Only confirmed, timely, recovery-admitted operations release proofs or secrets. Unknown writes are never retried automatically. An indeterminate verification cannot be reconciled into a login; require a fresh code. Status can reconcile management generations but never reveals secret material. Instances are safe to share across threads with thread-safe application dependencies.

Since:
1.0.0
  • Method Details

    • withIssuer

      Starts configuration with a trusted authenticator display issuer, not an OAuth issuer URL.
      Parameters:
      issuer - well-formed display issuer, 1–128 UTF-16 units, without colons, ISO controls, Unicode format/line/paragraph controls or leading/trailing whitespace
      Returns:
      a builder
      Since:
      1.0.0
    • getCredentialNamespace

      Returns the configured credential namespace.
      Returns:
      the namespace
      Since:
      1.0.0
    • getRecoveryEpoch

      Returns the fixed external recovery generation.
      Returns:
      the recovery epoch
      Since:
      1.0.0
    • beginEnrollmentResult

      Persist a browser-bound pending secret before releasing provisioning information. Management authorization is application-owned.
      Parameters:
      options - approved account, display label and optional exact replacement generation; the complete percent-encoded provisioning URI must fit 512 ASCII bytes
      browserBinding - unpredictable server-owned browser binding
      Returns:
      the canonical operation outcome
      Throws:
      IllegalArgumentException - if the encoded provisioning URI exceeds 512 bytes; validation precedes recovery admission, storage and entropy
      Since:
      1.0.0
    • confirmEnrollmentResult

      @CheckReturnValue public @NonNull TotpEnrollmentResult confirmEnrollmentResult(@NonNull String accountId, @NonNull String enrollmentId, @NonNull String code, @NonNull OperationBinding browserBinding)
      Atomically consumes pending enrollment, activates the factor, consumes its confirmation step and installs recovery verifiers.
      Parameters:
      accountId - approved stable account identifier
      enrollmentId - pending enrollment identifier
      code - submitted six ASCII digits, preserving leading zeros
      browserBinding - the original server-owned browser binding
      Returns:
      the canonical operation outcome
      Since:
      1.0.0
    • verifyResult

      @CheckReturnValue public @NonNull TotpVerificationResult verifyResult(@NonNull String accountId, @NonNull String code, @NonNull OperationBinding operationBinding)
      Verifies one code and commits replay consumption before releasing a TOTP proof. The application must atomically complete its current bound operation under recovery admission.
      Parameters:
      accountId - approved stable account identifier
      code - submitted six ASCII digits
      operationBinding - server-owned pending login or approved action binding
      Returns:
      the canonical operation outcome
      Since:
      1.0.0
    • consumeRecoveryCodeResult

      @CheckReturnValue public @NonNull RecoveryCodeUseResult consumeRecoveryCodeResult(@NonNull String accountId, @NonNull String recoveryCode, @NonNull OperationBinding operationBinding)
      Atomically consumes one recovery code and releases distinct recovery-method provenance. It does not prove current TOTP possession.
      Parameters:
      accountId - approved stable account identifier
      recoveryCode - submitted recovery code, accepting ASCII case folding and hyphens
      operationBinding - server-owned pending login or recovery action binding
      Returns:
      the canonical operation outcome
      Since:
      1.0.0
    • rotateRecoveryCodesResult

      @CheckReturnValue public @NonNull RecoveryCodeRotationResult rotateRecoveryCodesResult(@NonNull String accountId, @NonNull String expectedFactorId, @NonNull String expectedBatchId)
      Replaces the entire recovery batch only for the exact approved factor and batch generations. New plaintext is released only after a confirmed commit.
      Parameters:
      accountId - approved stable account identifier
      expectedFactorId - current factor generation from the authorized management context
      expectedBatchId - current recovery batch from that same context
      Returns:
      the canonical operation outcome
      Since:
      1.0.0
    • removeFactorResult

      @CheckReturnValue public @NonNull TotpFactorRemovalResult removeFactorResult(@NonNull String accountId, @NonNull String expectedFactorId)
      Removes the exact approved factor, pending enrollment and recovery batch while retaining permanent account and admission fences.
      Parameters:
      accountId - approved stable account identifier
      expectedFactorId - current factor generation from the approved management context
      Returns:
      the canonical operation outcome
      Since:
      1.0.0
    • cancelEnrollmentResult

      @CheckReturnValue public @NonNull TotpEnrollmentCancellationResult cancelEnrollmentResult(@NonNull String accountId, @NonNull String enrollmentId, @NonNull OperationBinding browserBinding)
      Cancels only the named browser-bound pending enrollment, preserving the active factor and attempt accounting.
      Parameters:
      accountId - approved stable account identifier
      enrollmentId - approved pending enrollment identifier
      browserBinding - original server-owned browser binding
      Returns:
      the canonical operation outcome
      Since:
      1.0.0
    • getStatusResult

      @CheckReturnValue public @NonNull TotpStatusResult getStatusResult(@NonNull String accountId)
      Reads active and pending generations and recovery counts without exposing secrets. Absence never authorizes a password-only fallback after namespace recovery.
      Parameters:
      accountId - authorized stable account identifier
      Returns:
      the canonical operation outcome
      Since:
      1.0.0
    • initializeNamespaceResult

      Initializes only a newly provisioned recovery generation under an explicit initialization permit. Normal operations never recreate a missing namespace root.
      Returns:
      the canonical operation outcome
      Since:
      1.0.0
    • resealStoreEntryResult

      Authenticates and reseals one permanent record with the active key under exact row and namespace predicates, preserving all semantic state and deadlines.
      Parameters:
      key - application-authorized maintenance address within this configured scope
      Returns:
      the canonical operation outcome
      Since:
      1.0.0
    • toString

      Redacts application configuration and identifiers.
      Overrides:
      toString in class Object
      Returns:
      a fixed description
      Since:
      1.0.0