mirror of
https://github.com/hanzoai/iam.git
synced 2026-11-19 18:37:16 +00:00
401 lines
14 KiB
Go
401 lines
14 KiB
Go
// Copyright 2026 Hanzo AI, Inc.
|
|
// SPDX-License-Identifier: MIT OR Apache-2.0
|
|
|
|
package factor
|
|
|
|
import (
|
|
"context"
|
|
"crypto/rand"
|
|
"encoding/base32"
|
|
"errors"
|
|
"strings"
|
|
|
|
"github.com/hanzoai/orm"
|
|
"github.com/pquerna/otp/totp"
|
|
"golang.org/x/crypto/bcrypt"
|
|
|
|
"github.com/hanzoai/iam/pkg/schema"
|
|
"github.com/hanzoai/iam/pkg/store"
|
|
)
|
|
|
|
// Package factor is the pure multi-factor DOMAIN — what a factor IS, whether a
|
|
// passcode verifies, which factors a user has, whether the org demands one, and
|
|
// how that state is written. It is the ONE implementation both the enrollment
|
|
// surface (internal/mfa) and the login-time second-factor gate (internal/oidc)
|
|
// call, so the Verify the challenge runs is the one enrollment's setup check uses
|
|
// and the Save every MFA write goes through cannot drift apart.
|
|
//
|
|
// It is a LEAF: it imports only store + schema, never authz or oidc. That is what
|
|
// lets the gate (in oidc, which authz imports) use it without an import cycle,
|
|
// while the enrollment surface (which does need authz) uses it too — one domain,
|
|
// two callers, no duplication. Radius and push are deliberately absent: no v2
|
|
// provider transport serves them, and a factor listed as available but unservable
|
|
// is an unusable challenge.
|
|
|
|
// The factor types, verbatim from v1 (object/mfa.go:42-48). "app" is TOTP — the
|
|
// name is v1's and it is in the serialized payload, so it does not get "improved".
|
|
const (
|
|
App = "app"
|
|
SMS = "sms"
|
|
Email = "email"
|
|
)
|
|
|
|
// Types lists the factors this package can project, in v1's order. It bounds
|
|
// AllProps: a factor absent here is never offered on a challenge.
|
|
var Types = []string{SMS, Email, App}
|
|
|
|
// errNoUser is the ONE answer to an unresolvable MFA subject.
|
|
var errNoUser = errors.New("user doesn't exist")
|
|
|
|
// Enroll generates a fresh TOTP secret for userID ("owner/name") and the
|
|
// otpauth:// URL that encodes it, using the RFC 6238 defaults every authenticator
|
|
// app assumes (the same totp.Generate defaults the enrollment surface uses). It
|
|
// persists NOTHING: enrollment is stateless and client-held until enable commits
|
|
// it.
|
|
func Enroll(userID, issuer string) (secret, url string, err error) {
|
|
if issuer == "" {
|
|
issuer = "Hanzo"
|
|
}
|
|
key, err := totp.Generate(totp.GenerateOpts{Issuer: issuer, AccountName: userID})
|
|
if err != nil {
|
|
return "", "", err
|
|
}
|
|
return key.Secret(), key.URL(), nil
|
|
}
|
|
|
|
// Verify reports whether passcode is currently valid for secret. It is the ONE
|
|
// TOTP verification point — enrollment's setup check and the login challenge call
|
|
// this same function, so they cannot drift apart. totp.Validate accepts the
|
|
// adjacent windows (skew 1), tolerating clock drift.
|
|
func Verify(secret, passcode string) bool {
|
|
if secret == "" || passcode == "" {
|
|
return false
|
|
}
|
|
return totp.Validate(passcode, secret)
|
|
}
|
|
|
|
// recoveryBytes is the entropy behind one recovery code: 20 bytes → 32 base32
|
|
// characters, the same strength as the TOTP secret it backs up.
|
|
const recoveryBytes = 20
|
|
|
|
// MintRecovery returns one fresh recovery code, in the clear, for the user to write
|
|
// down. It asks crypto/rand for a secret directly (not a formatted identifier).
|
|
func MintRecovery() (string, error) {
|
|
b := make([]byte, recoveryBytes)
|
|
if _, err := rand.Read(b); err != nil {
|
|
return "", err
|
|
}
|
|
return strings.ToLower(base32.StdEncoding.WithPadding(base32.NoPadding).EncodeToString(b)), nil
|
|
}
|
|
|
|
// HashRecovery is the digest a recovery code is STORED as. A recovery code is a
|
|
// bearer credential verified by equality alone, so — unlike the TOTP secret, which
|
|
// the verifier needs back in the clear — it hashes like a password.
|
|
func HashRecovery(plain string) (string, error) {
|
|
h, err := bcrypt.GenerateFromPassword([]byte(plain), bcrypt.DefaultCost)
|
|
return string(h), err
|
|
}
|
|
|
|
// HashRecoveryCodes digests each plaintext recovery code for storage — enrollment
|
|
// hands the user the plaintext (the QR's backup code) exactly once and keeps only
|
|
// the digest, so a database dump exposes no usable recovery credential.
|
|
func HashRecoveryCodes(plain []string) ([]string, error) {
|
|
out := make([]string, 0, len(plain))
|
|
for _, p := range plain {
|
|
h, err := HashRecovery(p)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
out = append(out, h)
|
|
}
|
|
return out, nil
|
|
}
|
|
|
|
// UseRecovery consumes one of the user's recovery codes, reporting whether code
|
|
// matched. A hit is DELETED from u.RecoveryCodes in place — one-time use — and the
|
|
// caller persists the row.
|
|
//
|
|
// Stored codes are bcrypt digests, but every code migrated from v1 is PLAINTEXT
|
|
// (object/mfa.go:81 compares in the clear), so a stored value that is not a digest
|
|
// is compared literally. The algorithm is a property of the stored value, never a
|
|
// constant — the same rule the password path lives by. A legacy hit is spent and
|
|
// removed like any other, so the plaintext dies on first use.
|
|
func UseRecovery(u *schema.User, code string) bool {
|
|
if u == nil || code == "" {
|
|
return false
|
|
}
|
|
for i, stored := range u.RecoveryCodes {
|
|
if !recoveryMatches(stored, code) {
|
|
continue
|
|
}
|
|
u.RecoveryCodes = append(u.RecoveryCodes[:i:i], u.RecoveryCodes[i+1:]...)
|
|
return true
|
|
}
|
|
return false
|
|
}
|
|
|
|
// recoveryMatches compares one presented code against one stored value, choosing
|
|
// the comparison from what the value IS: a bcrypt digest is verified with bcrypt,
|
|
// a v1-era plaintext by equality.
|
|
func recoveryMatches(stored, code string) bool {
|
|
if isBcrypt(stored) {
|
|
return bcrypt.CompareHashAndPassword([]byte(stored), []byte(code)) == nil
|
|
}
|
|
return stored != "" && stored == code
|
|
}
|
|
|
|
// isBcrypt reports whether s is a bcrypt digest by asking the library's own parser
|
|
// (bcrypt.Cost), so the answer comes from the format itself rather than a guess.
|
|
func isBcrypt(s string) bool {
|
|
_, err := bcrypt.Cost([]byte(s))
|
|
return err == nil
|
|
}
|
|
|
|
// Enabled reports whether the user has multi-factor sign-in on. The predicate is
|
|
// PreferredMfaType != "" and nothing else (v1 object/user.go:1641): the per-factor
|
|
// enabled flags say which factors exist, not whether the gate runs.
|
|
//
|
|
// It is only a truthful answer while [Prefer] is the sole writer of that column,
|
|
// which is the invariant Prefer exists to hold: a preferred factor nobody enrolled
|
|
// told the gate "this account has a second factor" and then left it nothing to ask
|
|
// for, so the sign-in reported MFA on and required the password alone.
|
|
func Enabled(u *schema.User) bool { return u != nil && u.PreferredMfaType != "" }
|
|
|
|
// Has reports whether the account actually HOLDS mfaType — the material to verify
|
|
// it with is on the row. It is [Props]'s own answer, named so that a policy decision
|
|
// about a factor reads as a predicate instead of a projection.
|
|
func Has(u *schema.User, mfaType string) bool { return Props(u, mfaType).Enabled }
|
|
|
|
// Held lists the factors the account holds, in [Types] order.
|
|
func Held(u *schema.User) []string {
|
|
held := make([]string, 0, len(Types))
|
|
for _, t := range Types {
|
|
if Has(u, t) {
|
|
held = append(held, t)
|
|
}
|
|
}
|
|
return held
|
|
}
|
|
|
|
// Add records that the account now holds mfaType. secret is the verifier's material
|
|
// and is meaningful only for [App] — a delivered factor's "secret" is the address
|
|
// itself, which the row already carries, so possession is a flag.
|
|
//
|
|
// This and [Remove] are the ONLY writers of the per-factor columns. Before them
|
|
// MfaPhoneEnabled and MfaEmailEnabled had four readers and no writer at all: the
|
|
// gate consulted flags nothing could ever set, so a texted or emailed second factor
|
|
// was unreachable for every account that had not been edited in the database.
|
|
//
|
|
// It does not touch the preference — [Prefer] owns that, so "the account holds this"
|
|
// and "the account is asked for this first" stay two decisions.
|
|
func Add(u *schema.User, mfaType, secret string) {
|
|
if u == nil {
|
|
return
|
|
}
|
|
switch mfaType {
|
|
case App:
|
|
u.TotpSecret = secret
|
|
case SMS:
|
|
u.MfaPhoneEnabled = true
|
|
case Email:
|
|
u.MfaEmailEnabled = true
|
|
}
|
|
}
|
|
|
|
// Remove records that the account no longer holds mfaType, discarding its verifier
|
|
// material. The preference is left to [Prefer], which repoints it at a factor that
|
|
// remains.
|
|
func Remove(u *schema.User, mfaType string) {
|
|
if u == nil {
|
|
return
|
|
}
|
|
switch mfaType {
|
|
case App:
|
|
u.TotpSecret = ""
|
|
case SMS:
|
|
u.MfaPhoneEnabled = false
|
|
case Email:
|
|
u.MfaEmailEnabled = false
|
|
}
|
|
}
|
|
|
|
// ErrNotHeld is the refusal when a preference names a factor the account does not
|
|
// hold.
|
|
var ErrNotHeld = errors.New("that factor is not enrolled on this account")
|
|
|
|
// Prefer points the account's preferred factor at mfaType. It is the ONE writer of
|
|
// PreferredMfaType, and it holds the invariant the login gate depends on: the
|
|
// preferred type names a factor the account actually HOLDS.
|
|
//
|
|
// mfaType "" means "whatever is left" — it repoints at the first held factor and
|
|
// clears the column when none remains, which is what [Remove] needs so that dropping
|
|
// the preferred factor cannot leave the preference dangling.
|
|
//
|
|
// A named factor the account does not hold is refused with [ErrNotHeld] rather than
|
|
// stored. Storing it was the whole defect: PreferredMfaType accepted any string —
|
|
// "sms" with nothing enrolled, or "carrier-pigeon" — and since [Enabled] reads that
|
|
// column, the account reported multi-factor sign-in while the gate had no factor to
|
|
// challenge and let the password through alone.
|
|
func Prefer(u *schema.User, mfaType string) error {
|
|
if u == nil {
|
|
return errNoUser
|
|
}
|
|
if mfaType == "" {
|
|
u.PreferredMfaType = ""
|
|
if held := Held(u); len(held) > 0 {
|
|
u.PreferredMfaType = held[0]
|
|
}
|
|
return nil
|
|
}
|
|
if !Has(u, mfaType) {
|
|
return ErrNotHeld
|
|
}
|
|
u.PreferredMfaType = mfaType
|
|
return nil
|
|
}
|
|
|
|
// Destination is where a DELIVERED factor's code is sent: the address the ACCOUNT
|
|
// holds, resolved from the factor type and from nothing a caller said. Empty means
|
|
// the account has no address for that factor, which is a refusal — a challenge
|
|
// cannot be answered over a channel the account does not own.
|
|
//
|
|
// It is domain, not transport, and it lives here rather than beside either caller
|
|
// because the send and the check MUST resolve the same address. When the challenge
|
|
// sends to one spelling and the verify looks up another, the correct code is refused;
|
|
// see otp.Receiver, which is the other half of that guarantee.
|
|
func Destination(u *schema.User, mfaType string) string {
|
|
if u == nil {
|
|
return ""
|
|
}
|
|
switch mfaType {
|
|
case SMS:
|
|
return store.NormalizePhone(u.Phone)
|
|
case Email:
|
|
return u.Email
|
|
}
|
|
return ""
|
|
}
|
|
|
|
// Delivered reports whether mfaType is a factor whose code has to be SENT — as
|
|
// opposed to [App], which the authenticator derives locally and which therefore
|
|
// works with no notify bound at all.
|
|
func Delivered(mfaType string) bool { return mfaType == SMS || mfaType == Email }
|
|
|
|
// Prompt reports whether the organization REQUIRES a factor the user has not
|
|
// enrolled yet — the sign-in must divert to enrollment before it can finish. The
|
|
// user's own MfaItems override the org's entirely when present (not merge: v1
|
|
// object/organization.go:770-792), so a per-user policy is a replacement.
|
|
func Prompt(org *schema.Organization, u *schema.User) bool {
|
|
if org == nil || u == nil {
|
|
return false
|
|
}
|
|
items := org.MfaItems
|
|
if len(u.MfaItems) > 0 {
|
|
items = u.MfaItems
|
|
}
|
|
for _, item := range items {
|
|
if item == nil || item.Rule != "Required" {
|
|
continue
|
|
}
|
|
switch item.Name {
|
|
case Email:
|
|
if !u.MfaEmailEnabled {
|
|
return true
|
|
}
|
|
case SMS:
|
|
if !u.MfaPhoneEnabled {
|
|
return true
|
|
}
|
|
case App:
|
|
if u.TotpSecret == "" {
|
|
return true
|
|
}
|
|
}
|
|
}
|
|
return false
|
|
}
|
|
|
|
// Props projects one factor of the user for a client, ALWAYS masked: Secret and
|
|
// RecoveryCodes are never populated (and are json:"-" besides). The login-gate
|
|
// verifier reads u.TotpSecret directly, so this projection has no unmasked mode to
|
|
// misuse.
|
|
func Props(u *schema.User, mfaType string) *schema.MfaProps {
|
|
p := &schema.MfaProps{MfaType: mfaType}
|
|
if u == nil {
|
|
return p
|
|
}
|
|
switch mfaType {
|
|
case SMS:
|
|
p.Enabled = u.MfaPhoneEnabled
|
|
if p.Enabled {
|
|
p.CountryCode = u.CountryCode
|
|
}
|
|
case Email:
|
|
p.Enabled = u.MfaEmailEnabled
|
|
case App:
|
|
p.Enabled = u.TotpSecret != ""
|
|
}
|
|
if !p.Enabled {
|
|
return &schema.MfaProps{MfaType: mfaType}
|
|
}
|
|
p.IsPreferred = u.PreferredMfaType == mfaType
|
|
return p
|
|
}
|
|
|
|
// AllProps projects every factor this package serves, masked, in v1's order.
|
|
func AllProps(u *schema.User) []*schema.MfaProps {
|
|
all := make([]*schema.MfaProps, 0, len(Types))
|
|
for _, t := range Types {
|
|
all = append(all, Props(u, t))
|
|
}
|
|
return all
|
|
}
|
|
|
|
// Copy overwrites dst's multi-factor state with src's, and nothing else. It is the
|
|
// ONE declaration of which columns ARE multi-factor state, so every writer agrees
|
|
// on the set by construction: Save overlays a caller's factors onto the STORED row
|
|
// through this, which is what makes an MFA write column-scoped — the request's user
|
|
// value never reaches the store, so it cannot carry isAdmin along and self-promote.
|
|
func Copy(dst, src *schema.User) {
|
|
if dst == nil || src == nil {
|
|
return
|
|
}
|
|
dst.PreferredMfaType = src.PreferredMfaType
|
|
dst.RecoveryCodes = src.RecoveryCodes
|
|
dst.TotpSecret = src.TotpSecret
|
|
// The per-user policy: which factors this account MUST hold. Prompt reads it in
|
|
// preference to the organization's, so an update that leaves it behind does not
|
|
// merely lose a setting — it turns a required second factor optional.
|
|
dst.MfaItems = src.MfaItems
|
|
dst.MfaPhoneEnabled = src.MfaPhoneEnabled
|
|
dst.MfaEmailEnabled = src.MfaEmailEnabled
|
|
dst.MfaRadiusEnabled = src.MfaRadiusEnabled
|
|
dst.MfaRadiusUsername = src.MfaRadiusUsername
|
|
dst.MfaRadiusProvider = src.MfaRadiusProvider
|
|
dst.MfaPushEnabled = src.MfaPushEnabled
|
|
dst.MfaPushReceiver = src.MfaPushReceiver
|
|
dst.MfaPushProvider = src.MfaPushProvider
|
|
dst.MfaRememberDeadline = src.MfaRememberDeadline
|
|
dst.MfaRememberDigest = src.MfaRememberDigest
|
|
}
|
|
|
|
// Save writes u's multi-factor state — and ONLY that — onto its stored row. It is
|
|
// the single write point for every MFA mutation the login gate makes: spend a
|
|
// recovery code, remember a device. The scoping is what makes it safe: the row is
|
|
// loaded fresh and Copy overlays exactly the multi-factor columns, so an isAdmin,
|
|
// a balance, or a password digest arriving on an MFA request reaches nothing.
|
|
func Save(ctx context.Context, db orm.DB, u *schema.User) error {
|
|
if u == nil {
|
|
return errNoUser
|
|
}
|
|
stored, err := store.GetUserByName(ctx, db, u.Owner, u.Name)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
if stored == nil {
|
|
return errNoUser
|
|
}
|
|
Copy(stored, u)
|
|
return stored.UpdateCtx(ctx)
|
|
}
|