Shell Layer - MFA operations with side effects.
This is the SHELL layer for MFA operations:
All I/O and side effects happen here. Pure business logic is delegated to wagoe.user.core.mfa.
Shell Layer - MFA operations with side effects. This is the SHELL layer for MFA operations: - TOTP secret generation - TOTP code verification - Backup code generation (secure random) - QR code generation for authenticator apps All I/O and side effects happen here. Pure business logic is delegated to wagoe.user.core.mfa.
The Instant TOTP codes are checked at; nil reads the clock. Tests bind it so a code they generate cannot fall into the next 30 s window.
The Instant TOTP codes are checked at; nil reads the clock. Tests bind it so a code they generate cannot fall into the next 30 s window.
(audit-enrolment! mfa-service user-id email {:keys [ip-address user-agent]})Record a second factor set up at sign-in with the password alone; a failed
write is logged and does not undo it. context: :ip-address :user-agent.
Record a second factor set up at sign-in with the password alone; a failed write is logged and does not undo it. `context`: :ip-address :user-agent.
(check-code! user-repository user code)Verify code, spending it when it is a backup code.
Verify `code`, spending it when it is a backup code.
(create-mfa-service user-repository config)(create-mfa-service user-repository config opts)Factory function: Create MFA service instance.
Args: user-repository: IUserRepository implementation config: MFA configuration map opts: optional :audit-repository, which records a disable, and :auth-config, whose lockout policy a wrong disable proof counts towards
Returns: MFAService instance
Factory function: Create MFA service instance.
Args:
user-repository: IUserRepository implementation
config: MFA configuration map
opts: optional :audit-repository, which records a disable, and
:auth-config, whose lockout policy a wrong disable proof counts
towards
Returns:
MFAService instance(disable-mfa mfa-service user-id proof request-context)Turn MFA off for user-id once they prove it is them: proof is
{:password …} or {:code …}, a current TOTP or backup code, the only
proof a user without a password has. A wrong proof counts as a failed
login, so guessing locks the account as at sign-in, and a locked account
cannot disable. request-context carries :ip-address and :user-agent for
the audit entry.
Returns {:success? true}, or {:success? false :error {:type … :message …}}
— the ADR-036 §3 shape. :type is :cannot-disable, :proof-required,
:invalid-proof, :account-locked (with :retry-after) or
:mfa-disable-failed.
Turn MFA off for `user-id` once they prove it is them: `proof` is
`{:password …}` or `{:code …}`, a current TOTP or backup code, the only
proof a user without a password has. A wrong proof counts as a failed
login, so guessing locks the account as at sign-in, and a locked account
cannot disable. `request-context` carries :ip-address and :user-agent for
the audit entry.
Returns `{:success? true}`, or `{:success? false :error {:type … :message …}}`
— the ADR-036 §3 shape. `:type` is `:cannot-disable`, `:proof-required`,
`:invalid-proof`, `:account-locked` (with `:retry-after`) or
`:mfa-disable-failed`.(enable-mfa mfa-service user-id secret backup-codes verification-code)Enable MFA for a user after verifying setup.
Args: mfa-service: MFAService instance user-id: UUID of user enabling MFA secret: TOTP secret from setup backup-codes: Backup codes from setup verification-code: 6-digit code from authenticator app
Returns:
{:success? true}, or {:success? false :error {:type … :message …}} —
the ADR-036 §3 shape. A code that does not match is an answer, not an
exceptional condition. :type is :invalid-code, :cannot-enable or
:mfa-enable-failed.
Enable MFA for a user after verifying setup.
Args:
mfa-service: MFAService instance
user-id: UUID of user enabling MFA
secret: TOTP secret from setup
backup-codes: Backup codes from setup
verification-code: 6-digit code from authenticator app
Returns:
`{:success? true}`, or `{:success? false :error {:type … :message …}}` —
the ADR-036 §3 shape. A code that does not match is an answer, not an
exceptional condition. `:type` is `:invalid-code`, `:cannot-enable` or
`:mfa-enable-failed`.(generate-backup-code)Shell function: Generate a single secure backup code.
Returns: 12-character alphanumeric backup code
Side effects: Secure random generation
Shell function: Generate a single secure backup code. Returns: 12-character alphanumeric backup code Side effects: Secure random generation
(generate-backup-codes)(generate-backup-codes count)Shell function: Generate multiple backup codes.
Args: count: Number of backup codes to generate (default 10)
Returns: Vector of formatted backup codes
Side effects: Secure random generation
Shell function: Generate multiple backup codes. Args: count: Number of backup codes to generate (default 10) Returns: Vector of formatted backup codes Side effects: Secure random generation
(generate-qr-code-data-url totp-uri)Shell function: Generate QR code as a base64-encoded PNG data URL.
Args: totp-uri: TOTP URI string
Returns: Data URL string (data:image/png;base64,...) for use in <img> src attribute. Generated locally using ZXing — no external service required.
Shell function: Generate QR code as a base64-encoded PNG data URL. Args: totp-uri: TOTP URI string Returns: Data URL string (data:image/png;base64,...) for use in <img> src attribute. Generated locally using ZXing — no external service required.
(generate-totp-secret)Shell function: Generate a new TOTP secret.
Returns: Base32-encoded secret string for TOTP
Side effects: Secure random generation
Shell function: Generate a new TOTP secret. Returns: Base32-encoded secret string for TOTP Side effects: Secure random generation
(generate-totp-uri secret account-name issuer)Shell function: Generate TOTP URI for QR code.
Args: secret: Base32-encoded TOTP secret account-name: User identifier (usually email) issuer: Application name
Returns: TOTP URI string for QR code generation
Side effects: None (pure string generation)
Shell function: Generate TOTP URI for QR code. Args: secret: Base32-encoded TOTP secret account-name: User identifier (usually email) issuer: Application name Returns: TOTP URI string for QR code generation Side effects: None (pure string generation)
(get-mfa-status mfa-service user-id)Get MFA status for a user.
Args: mfa-service: MFAService instance user-id: UUID of user
Returns: MFA status map
Get MFA status for a user. Args: mfa-service: MFAService instance user-id: UUID of user Returns: MFA status map
(setup-mfa mfa-service user-id)Initiate MFA setup for a user.
Args: mfa-service: MFAService instance user-id: UUID of user setting up MFA
Returns:
{:success? true :secret … :qr-code-url … :backup-codes …}, or
{:success? false :error {:type … :message …}} — the ADR-036 §3 shape.
:type is :cannot-enable or :mfa-setup-failed.
Initiate MFA setup for a user.
Args:
mfa-service: MFAService instance
user-id: UUID of user setting up MFA
Returns:
`{:success? true :secret … :qr-code-url … :backup-codes …}`, or
`{:success? false :error {:type … :message …}}` — the ADR-036 §3 shape.
`:type` is `:cannot-enable` or `:mfa-setup-failed`.(setup-view mfa-service secret account-name backup-codes)What the setup step shows: secret as a QR code for account-name, and
the backup codes. Also what it shows again after a wrong first code.
What the setup step shows: `secret` as a QR code for `account-name`, and the backup codes. Also what it shows again after a wrong first code.
(verify-mfa-code _mfa-service user code)Verify MFA code for authentication.
Args: mfa-service: MFAService instance user: User entity code: 6-digit TOTP code or backup code
Returns: {:valid? boolean :used-backup-code? boolean :code-hash string (the matched backup code's stored hash)}
Spending the backup code is the caller's: ports/consume-backup-code.
Verify MFA code for authentication.
Args:
mfa-service: MFAService instance
user: User entity
code: 6-digit TOTP code or backup code
Returns:
{:valid? boolean
:used-backup-code? boolean
:code-hash string (the matched backup code's stored hash)}
Spending the backup code is the caller's: `ports/consume-backup-code`.(verify-totp-code code secret)Shell function: Verify TOTP code against secret.
Args: code: 6-digit TOTP code (string) secret: Base32-encoded TOTP secret
Returns: Boolean - true if code is valid
Side effects: Time-dependent verification
Shell function: Verify TOTP code against secret. Args: code: 6-digit TOTP code (string) secret: Base32-encoded TOTP secret Returns: Boolean - true if code is valid Side effects: Time-dependent verification
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |