Class TotpAuthenticator
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
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final classCaller-thread configuration builder. -
Method Summary
Modifier and TypeMethodDescriptionbeginEnrollmentResult(@NonNull TotpEnrollmentOptions options, @NonNull OperationBinding browserBinding) Persist a browser-bound pending secret before releasing provisioning information.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.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.consumeRecoveryCodeResult(@NonNull String accountId, @NonNull String recoveryCode, @NonNull OperationBinding operationBinding) Atomically consumes one recovery code and releases distinct recovery-method provenance.Returns the configured credential namespace.Returns the fixed external recovery generation.getStatusResult(@NonNull String accountId) Reads active and pending generations and recovery counts without exposing secrets.Initializes only a newly provisioned recovery generation under an explicit initialization permit.removeFactorResult(@NonNull String accountId, @NonNull String expectedFactorId) Removes the exact approved factor, pending enrollment and recovery batch while retaining permanent account and admission fences.Authenticates and reseals one permanent record with the active key under exact row and namespace predicates, preserving all semantic state and deadlines.rotateRecoveryCodesResult(@NonNull String accountId, @NonNull String expectedFactorId, @NonNull String expectedBatchId) Replaces the entire recovery batch only for the exact approved factor and batch generations.toString()Redacts application configuration and identifiers.verifyResult(@NonNull String accountId, @NonNull String code, @NonNull OperationBinding operationBinding) Verifies one code and commits replay consumption before releasing a TOTP proof.withIssuer(@NonNull String issuer) Starts configuration with a trusted authenticator display issuer, not an OAuth issuer URL.
-
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
@CheckReturnValue public @NonNull TotpEnrollmentRequestResult beginEnrollmentResult(@NonNull TotpEnrollmentOptions options, @NonNull OperationBinding browserBinding) 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 bytesbrowserBinding- 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 identifierenrollmentId- pending enrollment identifiercode- submitted six ASCII digits, preserving leading zerosbrowserBinding- 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 identifiercode- submitted six ASCII digitsoperationBinding- 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 identifierrecoveryCode- submitted recovery code, accepting ASCII case folding and hyphensoperationBinding- 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 identifierexpectedFactorId- current factor generation from the authorized management contextexpectedBatchId- 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 identifierexpectedFactorId- 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 identifierenrollmentId- approved pending enrollment identifierbrowserBinding- original server-owned browser binding- Returns:
- the canonical operation outcome
- Since:
- 1.0.0
-
getStatusResult
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
@CheckReturnValue public @NonNull TotpStoreResealResult resealStoreEntryResult(@NonNull TotpStoreKey key) 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
-