@askrjs/auth/mfa

CoseAlgorithmtype

CoseAlgorithm: -7 | -257 | -8

Algorithm identifier persisted with a supported WebAuthn credential.

createTotpProvisioningUri

createTotpProvisioningUri: (input: { secret: string; issuer: string; account: string; } & TotpOptions) => string

Build an otpauth:// URI for authenticator enrollment.

generateTotpSecret

generateTotpSecret: (options?: { byteLength?: number; }) => string

Generate a cryptographically random Base32 TOTP secret.

MfaValidationError

MfaValidationError: typeof MfaValidationError

Error raised when MFA input or credentials fail validation.

code

Error category used for programmatic handling.

name

Error category used for programmatic handling.

MfaValidationErrorCodetype

MfaValidationErrorCode: "malformed-input" | "credential-mismatch" | "invalid-challenge" | "invalid-origin" | "invalid-rp-id" | "user-presence-required" | "user-verification-required" | "unsupported-algorithm" | "invalid-attestation" | "invalid-signature" | "counter-rollback"

Stable failure codes for MFA and WebAuthn validation.

TotpAlgorithmtype

TotpAlgorithm: "SHA-1" | "SHA-256" | "SHA-512"

Hash algorithms supported by TOTP.

TotpOptionstype

TotpOptions: any

Shared TOTP generation and verification settings.

algorithm

HMAC hash algorithm. Defaults to SHA-1.

digits

Number of digits in generated codes.

periodSeconds

Validity period in seconds.

TotpVerificationResulttype

TotpVerificationResult: {
  valid: true;
  /**
   * Accepted moving counter. The application must atomically reject an already-consumed
   * counter and persist a newly accepted counter to provide replay protection.
   */
  counter: number;
  /** Matched offset from the current counter; useful for application-owned clock-drift policy. */
  drift: number;
} | {
  valid: false;
  counter?: never;
  drift?: never;
}

Result of verifying a TOTP code.

verifyTotpCode

verifyTotpCode: (input: VerifyTotpOptions) => Promise<TotpVerificationResult>

Verify a TOTP code with a bounded clock-drift window. The window is scanned from -window through +window. If the same code matches more than one counter, the last match wins, so the greatest numeric drift (toward +window) is returned. A valid cryptographic result alone does not prevent replay. The caller must atomically consume and persist the returned counter before granting access: ``ts const result = await verifyTotpCode({ secret, code }); if (result.valid && await counters.consume(result.counter)) grantAccess();

VerifyTotpOptionstype

VerifyTotpOptions: any

Input required to verify one TOTP code.

secret

Base32-encoded shared secret.

code

User-entered one-time code.

at

Non-negative Unix time in milliseconds, or a valid Date. Defaults to the current time.

window

Number of adjacent periods accepted on either side.

verifyWebAuthnAuthentication

verifyWebAuthnAuthentication: (input: WebAuthnAuthenticationInput) => Promise<{ signCount: number; backupEligible: boolean; backedUp: boolean; }>

Verify a WebAuthn assertion against a stored credential.

verifyWebAuthnRegistration

verifyWebAuthnRegistration: (input: WebAuthnRegistrationInput) => Promise<WebAuthnRegistrationResult>

Verify a WebAuthn registration ceremony and decode its public key.

WebAuthnAuthenticationInputtype

WebAuthnAuthenticationInput: any

Server-side WebAuthn authentication ceremony data.

credentialId

Credential identifier returned by the browser.

storedCredentialId

Credential identifier stored during registration.

publicKeyJwk

Stored public-key JWK.

authenticatorData

Authenticator data bytes.

clientDataJSON

Browser client-data JSON bytes.

signature

Assertion signature bytes.

expectedChallenge

Challenge originally issued by the server.

allowedOrigins

Allowed origins for this ceremony.

rpId

Relying-party identifier.

signCount

Previously stored signature counter.

requireUserVerification

Require user verification.

WebAuthnRegistrationInputtype

WebAuthnRegistrationInput: any

Server-side WebAuthn registration ceremony data.

credentialId

Credential identifier returned by the browser.

clientDataJSON

Browser client-data JSON bytes.

attestationObject

Browser attestation object bytes.

expectedChallenge

Challenge originally issued by the server.

allowedOrigins

Allowed origins for this ceremony.

rpId

Relying-party identifier.

requireUserVerification

Require user verification.

WebAuthnRegistrationResulttype

WebAuthnRegistrationResult: any

Verified credential data persisted after registration.

credentialId

Credential identifier to persist.

publicKeyJwk

Public key to persist.

algorithm

COSE algorithm identifier.

signCount

Initial signature counter.

aaguid

Authenticator AAGUID.

backupEligible

Whether the credential may be backed up.

backedUp

Whether the credential is currently backed up.