Files
zeekay ef2f42a2ec Decide SuperAdmin on the row's own org
schema.User.SuperAdmin is the one predicate: a person whose row's owner
is the admin org. The Guard sets Principal.Sudo from it when it loads
the caller, and assume/release, device approval, unlink, the bootstrap
credential freeze and the registry push gate ask the row directly.
store.IsSuperAdmin, which also admitted a membership of the admin org,
is gone. A brand org's user added to the admin org is an ordinary
member of their own org, and a service account or program in the admin
org is never SuperAdmin.

hanzoai/authz v1.10.42 reads the same rule off a token (Claims.Sudo on
orgs[0]) and lets a membership of the admin org open nothing, so such a
member no longer reads or edits the admin org's registry row either.
The token IAM mints is unchanged: orgs still opens with the row's
owner.

Two protective gates keep the whole admin org, machines and unheld
names included: no secret key names an account there
(store.SuperAdminKey), and only a SuperAdmin writes one
(users.Authorize). Both read the owner as written, so neither reads the
store.

Every request the Guard admits for a SuperAdmin is recorded as a
superadmin audit row, PlatformWritten, with its method, address, answer
and client address; so is a SuperAdmin's unlink of someone else's
sign-in method and a device approval into another org.

TestEverySuperAdminGateAdmitsTheAdminOrgsPeopleOnly drives ten
SuperAdmin-only requests through the router as two SuperAdmins, a brand
admin holding an admin-org membership and two admin-org machines, and
reads the trail row each one leaves.

Claude-Session: https://claude.ai/code/session_01HuMDfgFssPUptYUzgZ6Cp8
2026-09-27 19:24:51 -07:00

489 lines
18 KiB
Go

// Copyright 2026 Hanzo AI, Inc.
// SPDX-License-Identifier: MIT OR Apache-2.0
// Package mfa serves the multi-factor ENROLMENT surface — adding a second factor to
// an account, dropping one, and choosing which is asked for first. Its counterpart
// is the login-time gate (internal/oidc/mfa_gate.go): this decides what factors an
// account HAS, that decides when a sign-in must present one.
//
// All three factors enrol the same way, and there is only one way: INITIATE, which
// hands out (or sends) the material, then ENABLE, which requires that material back
// before it writes anything. What comes back is the proof of possession —
//
// app the passcode an authenticator derives from the secret initiate handed out
// sms the code texted to the number ON THE ACCOUNT
// email the code mailed to the address ON THE ACCOUNT
//
// — and for the two delivered factors the address IS the factor, so receiving the
// code is the whole proof. The destination is never taken from the request: an
// enrolment that let the caller name it would enrol an attacker's phone.
//
// There is no separate "check my code before I commit" step. There was one, and it was
// ADVISORY — it verified a passcode and parked nothing, while enable wrote on the
// strength of a secret field alone. Two calls where the first is unenforced is how a
// factor got switched on that no code could ever answer, so the check moved to where
// the write is: enable verifies, then writes. A wrong code is the same error message
// either way, and the person retries.
//
// Enrolment is SELF-SERVICE: every handler acts on the AUTHENTICATED caller's own
// record (principal.From), so the routes register AFTER the Guard — they need the
// Principal. Touching a DIFFERENT user's factors requires admin authority over that
// org, authorized through the SAME seam a SCIM write uses (authz.Can); the general
// user-write policy correctly refuses a non-admin writing a user row, so
// self-enrolment is authorized by self-ownership (target == principal), NOT by that
// policy.
//
// Adding or dropping a factor SIGNS OUT the account's other browsers. Turning 2FA on
// while a stolen session stayed live for its full 14 days was the same downgrade as
// not having the factor at all.
package mfa
import (
"encoding/json"
"net/http"
"os"
"strings"
"time"
"github.com/zap-proto/zip"
"github.com/hanzoai/orm"
"github.com/hanzoai/iam/internal/authz"
"github.com/hanzoai/iam/internal/mfa/factor"
"github.com/hanzoai/iam/internal/otp"
"github.com/hanzoai/iam/internal/principal"
"github.com/hanzoai/iam/internal/sessions"
"github.com/hanzoai/iam/internal/users"
"github.com/hanzoai/iam/pkg/schema"
"github.com/hanzoai/iam/pkg/store"
)
// The factor types ("app", "sms", "email") and the domain helpers are factor.App et
// al (internal/mfa/factor).
// Route registers the MFA endpoints on app. They are RAW handlers (not typed ops),
// so — like SCIM — each authorizes itself; callers register app AFTER the Guard so a
// verified Principal rides the request context.
//
// The surface hangs off the /v1/iam/mfa noun, and Path IS that noun: the factors an
// account holds. Dropping one is DELETE on them, because the method is what says
// what is being done — an address that changes with the operation gives a client one
// URL per verb. Which factor to drop is a FIELD (`mfaType`, absent meaning all), the
// same way the key type is a field of a mint: the moment a class becomes its own
// endpoint the classes drift.
const (
Path = "/v1/iam/mfa"
PathInitiate = "/v1/iam/mfa/setup/initiate"
PathEnable = "/v1/iam/mfa/setup/enable"
PathPreferred = "/v1/iam/mfa/preferred"
)
//go:generate go run github.com/zap-proto/zip/cmd/zipdoc
func Route(app *zip.Group, db orm.DB) {
app.Raw(http.MethodPost, PathInitiate, initiate(db))
app.Raw(http.MethodPost, PathEnable, enable(db))
app.Raw(http.MethodDelete, Path, disable(db))
app.Raw(http.MethodPost, PathPreferred, setPreferred(db))
}
// recoveryCount is how many recovery codes an enrolment mints. Eight, not one: a
// recovery code is spent on use, and one code is a single mistake away from an
// account nobody can get back into. There is no regeneration surface, so this IS the
// whole budget for the life of the factor.
const recoveryCount = 8
// setupReq is the union of fields the enrolment handshake posts. owner/name address
// the target user (default: the caller itself); mfaType names the factor; secret and
// passcode carry the proof of possession.
//
// RecoveryCodes is deliberately absent. Enrolment used to take the digests to store
// from the REQUEST, so "the codes the person was shown" and "the digests that were
// stored" were only equal if the client echoed them back correctly — and a client
// that sent none enrolled a factor with no way back in at all. They are minted here
// and returned once.
type setupReq struct {
Owner string `json:"owner"`
Name string `json:"name"`
MfaType string `json:"mfaType"`
Secret string `json:"secret"`
Passcode string `json:"passcode"`
}
// target resolves the (owner, name) an MFA request addresses and authorizes it:
// the caller may always manage its OWN record; touching another user's MFA
// requires admin authority over that org (authz.Can — the seam SCIM writes use),
// and a SuperAdmin's factors are touched only by a SuperAdmin (users.Authorize).
// An unauthenticated caller fails closed (the Guard already required a bearer, so
// this is defense in depth). Returns a zip error to return verbatim on refusal.
func target(c *zip.Ctx, db orm.DB, req *setupReq) (owner, name string, err error) {
p, present := principal.From(c.Context())
if !present {
return "", "", zip.ErrUnauthorized("authentication required")
}
owner, name = strings.TrimSpace(req.Owner), strings.TrimSpace(req.Name)
if owner == "" || name == "" {
owner, name = p.Org, p.User // default: the caller itself
}
self := owner == p.Org && name == p.User
if !self && !authz.Can(c.Context(), "PUT", "users", owner, name) {
return "", "", zip.ErrForbidden("forbidden")
}
if err := users.Authorize(c.Context(), owner); err != nil {
return "", "", err
}
return owner, name, nil
}
// initiate starts enrolling a factor and hands over whatever the person needs to prove
// they hold it:
//
// app a fresh secret and the otpauth:// URL to render as a QR code
// sms a code texted to the number on the account
// email a code mailed to the address on the account
//
// Nothing is switched on yet, so abandoning this step leaves the account exactly as
// it was. Response: {status:"ok", data:{mfaType, secret, url}} — secret and url only
// for the authenticator.
func initiate(db orm.DB) zip.Handler {
return func(c *zip.Ctx) error {
var req setupReq
if err := decode(c, &req); err != nil {
return c.JSON(400, errResp("invalid body"))
}
owner, name, err := target(c, db, &req)
if err != nil {
return err
}
mfaType := factorOf(&req)
u, err := load(c, db, owner, name)
if err != nil || u == nil {
return err
}
if mfaType == factor.App {
secret, url, err := factor.Enroll(owner+"/"+name, issuer(owner))
if err != nil {
return c.JSON(500, errResp("failed to generate secret"))
}
return c.JSON(200, okData(map[string]any{"mfaType": mfaType, "secret": secret, "url": url}))
}
// A delivered factor's material is a code sent to the address the ACCOUNT holds.
// factor.Destination resolves it and add() verifies against the same call, so the
// address a code went to and the address that accepts it back are one value.
dest := factor.Destination(u, mfaType)
if dest == "" {
return c.JSON(200, errResp("add a "+addressWord(mfaType)+" to your account first"))
}
if err := otp.Issue(c.Context(), db, owner, dest, c.Fiber().IP(), u, nowFunc()); err != nil {
return c.JSON(200, errResp("the code could not be sent: "+err.Error()))
}
return c.JSON(200, okData(map[string]any{"mfaType": mfaType}))
}
}
// enable finishes the enrolment: from here the account's sign-ins ask for this factor.
// It requires the proof initiate handed out — a passcode from the authenticator, or the
// code that was sent — and verifies it BEFORE writing anything.
//
// Verifying BEFORE writing is what keeps a client that never completed the proof —
// a skipped verify step, a QR scanned into the wrong app, a bug — from switching on
// a factor no code can satisfy. That would lock the account out with no
// self-service way back: the gate holds the sign-in before minting, so the person
// could not obtain the bearer that disable requires.
//
// The recovery codes are minted here and returned ONCE, on the first factor the
// account adds. Answering with them is the way back in when no factor can be
// produced, so they are the same value the row's digests were made from — by
// construction, not by a client echoing them back.
func enable(db orm.DB) zip.Handler {
return func(c *zip.Ctx) error {
var req setupReq
if err := decode(c, &req); err != nil {
return c.JSON(400, errResp("invalid body"))
}
owner, name, err := target(c, db, &req)
if err != nil {
return err
}
mfaType := factorOf(&req)
u, err := load(c, db, owner, name)
if err != nil || u == nil {
return err
}
if req.Passcode == "" {
return c.JSON(200, errResp("the code from your "+proofWord(mfaType)+" is required"))
}
switch mfaType {
case factor.App:
if req.Secret == "" {
return c.JSON(200, errResp("secret is required"))
}
if !factor.Verify(req.Secret, req.Passcode) {
return c.JSON(200, errResp("the code is incorrect"))
}
factor.Add(u, mfaType, req.Secret)
case factor.SMS, factor.Email:
ok, err := otp.Consume(c.Context(), db, u, factor.Destination(u, mfaType), req.Passcode, nowFunc())
if err != nil {
return c.JSON(500, errResp("server_error"))
}
if !ok {
return c.JSON(200, errResp("the code is incorrect or has expired"))
}
factor.Add(u, mfaType, "")
default:
return c.JSON(200, errResp("unsupported factor: "+mfaType))
}
// Recovery codes belong to the ACCOUNT, not to a factor: mint them with the first
// one and leave them alone after, so adding a second factor cannot invalidate the
// codes somebody already wrote down.
var plain []string
if len(u.RecoveryCodes) == 0 {
if plain, err = mintRecovery(u); err != nil {
return c.JSON(500, errResp("server_error"))
}
}
// The FIRST factor added becomes the preferred one; a later one does not steal the
// preference — somebody adding email as a backup to their authenticator still
// expects to be asked for the authenticator. setPreferred is how that changes.
if !factor.Has(u, u.PreferredMfaType) {
if err := factor.Prefer(u, mfaType); err != nil {
return c.JSON(500, errResp("server_error"))
}
}
if err := save(c, db, u); err != nil {
return c.JSON(500, errResp("server_error"))
}
data := map[string]any{"mfaType": mfaType, "preferredMfaType": u.PreferredMfaType}
if len(plain) > 0 {
data["recoveryCodes"] = plain
}
return c.JSON(200, okData(data))
}
}
// disable turns a factor off, so sign-in stops asking for it. Naming no factor turns
// off ALL of them — the reset path. People may do this for themselves; doing it for
// somebody else takes an administrator, which is what makes it the way back in when a
// phone is lost.
//
// The recovery codes go with the last factor: they are the way past a challenge, so
// keeping them alive for an account with nothing to challenge would leave a standing
// credential behind.
func disable(db orm.DB) zip.Handler {
return func(c *zip.Ctx) error {
var req setupReq
if err := decode(c, &req); err != nil {
return c.JSON(400, errResp("invalid body"))
}
owner, name, err := target(c, db, &req)
if err != nil {
return err
}
u, err := load(c, db, owner, name)
if err != nil || u == nil {
return err
}
drop := factor.Types
if t := strings.TrimSpace(req.MfaType); t != "" {
drop = []string{t}
}
for _, t := range drop {
factor.Remove(u, t)
}
// "" repoints the preference at whatever is left, and clears it when nothing is —
// so the account can never claim a factor it no longer holds.
if err := factor.Prefer(u, ""); err != nil {
return c.JSON(500, errResp("server_error"))
}
if len(factor.Held(u)) == 0 {
u.RecoveryCodes = nil
}
if err := save(c, db, u); err != nil {
return c.JSON(500, errResp("server_error"))
}
return c.JSON(200, okData(nil))
}
}
// setPreferred picks which second factor an account is asked for first when it has
// more than one. Only a factor the account actually holds: storing an unheld one told
// the login gate "MFA is on" — factor.Enabled reads that column — while leaving it
// nothing to ask for, so the sign-in required the password alone.
func setPreferred(db orm.DB) zip.Handler {
return func(c *zip.Ctx) error {
var req setupReq
if err := decode(c, &req); err != nil {
return c.JSON(400, errResp("invalid body"))
}
owner, name, err := target(c, db, &req)
if err != nil {
return err
}
if strings.TrimSpace(req.MfaType) == "" {
return c.JSON(200, errResp("mfaType is required"))
}
u, err := load(c, db, owner, name)
if err != nil || u == nil {
return err
}
if err := factor.Prefer(u, req.MfaType); err != nil {
return c.JSON(200, errResp(err.Error()))
}
if err := save(c, db, u); err != nil {
return c.JSON(500, errResp("server_error"))
}
return c.JSON(200, okData(nil))
}
}
// ---- helpers ----
// nowFunc is the clock, injected the same way the rest of the repo injects one.
var nowFunc = time.Now
// decode reads the request: the JSON body when there is one, then the QUERY STRING
// for the half of a request a URL is allowed to carry.
//
// WHAT IT ADDRESSES falls back to the query. owner and name say which account,
// mfaType says which factor, and a URL naming what it acts on is what a URL is
// for. It is also the precedence zip's typed binder applies to every typed op, and
// it is the whole reason this surface was usable at all: the portal posts those
// fields on the query with an empty body, three of the five handlers read only the
// body, and so `enable` and `preferred` answered 400 "invalid body" to the exact
// requests the shipped client sends. Nobody could add a second factor, and an
// organization that required one was locked out.
//
// WHAT IT PROVES does not. `secret` is the TOTP seed: not a token but the factor
// itself, enough to derive every passcode the account will ever accept, for as long
// as the enrolment lasts. `passcode` is a live one. A URL is the part of a request
// that gets written down — the ingress access log, every proxy in front of it, the
// browser's history — so a seed that reaches the query is a second factor that
// belongs to whoever reads logs. Both are read from the BODY alone, which is the
// same line every typed op's credential field draws with `url:"-"`. One rule about
// what a URL carries, whether the binder is zip's or this one.
func decode(c *zip.Ctx, req *setupReq) error {
if body := c.Body(); len(body) > 0 {
if err := json.Unmarshal(body, req); err != nil {
return err
}
}
addr := func(dst *string, key string) {
if *dst == "" {
*dst = c.Query(key)
}
}
addr(&req.Owner, "owner")
addr(&req.Name, "name")
addr(&req.MfaType, "mfaType")
return nil
}
// factorOf is the factor a request addresses, defaulting to the authenticator — the
// factor the account security page enrols when it names none.
func factorOf(req *setupReq) string {
if t := strings.TrimSpace(req.MfaType); t != "" {
return t
}
return factor.App
}
// load resolves the target user and answers the request itself when there is none, so
// every handler reads the same two lines. A nil user with a nil error means the answer
// is already written.
func load(c *zip.Ctx, db orm.DB, owner, name string) (*schema.User, error) {
u, err := store.GetUserByName(c.Context(), db, owner, name)
if err != nil {
return nil, c.JSON(500, errResp("server_error"))
}
if u == nil {
return nil, c.JSON(404, errResp("user not found"))
}
return u, nil
}
// save commits an MFA change through factor.Save — the column-scoped write, so a
// request cannot carry an isAdmin along — and then ends the account's OTHER sessions.
//
// The revocation is part of the write, not a courtesy. A session established before
// the factor existed reaches loginGrant with no credential at all and keeps minting
// authorization codes for the full 14-day session life, so switching 2FA on evicted
// nobody — including whoever the second factor was being added because of. The
// session making THIS request is kept: it just proved the factor.
func save(c *zip.Ctx, db orm.DB, u *schema.User) error {
// An open "don't ask again" window short-circuits the whole gate, so a window
// opened against the OLD factor set would skip the new one. Changing a factor
// closes it: the next sign-in on every browser asks for the factor once.
u.MfaRememberDeadline, u.MfaRememberDigest = "", ""
if err := factor.Save(c.Context(), db, u); err != nil {
return err
}
sessions.RevokeOthers(c.Context(), c.Fiber(), db, u.Owner, u.Name)
return nil
}
// mintRecovery mints the account's recovery codes, returning the plaintext to show
// once and storing only the digests.
func mintRecovery(u *schema.User) ([]string, error) {
plain := make([]string, 0, recoveryCount)
for range recoveryCount {
code, err := factor.MintRecovery()
if err != nil {
return nil, err
}
plain = append(plain, code)
}
hashed, err := factor.HashRecoveryCodes(plain)
if err != nil {
return nil, err
}
u.RecoveryCodes = hashed
return plain, nil
}
// issuer is the otpauth issuer label the authenticator app shows: an explicit
// IAM_MFA_ISSUER override (white-label brand), else the account's org, else Hanzo.
func issuer(owner string) string {
if v := strings.TrimSpace(os.Getenv("IAM_MFA_ISSUER")); v != "" {
return v
}
if owner != "" {
return owner
}
return "Hanzo"
}
// addressWord and proofWord name a factor's address and its proof the way a person
// would, for a message they can act on.
func addressWord(mfaType string) string {
if mfaType == factor.SMS {
return "phone number"
}
return "email address"
}
func proofWord(mfaType string) string {
switch mfaType {
case factor.SMS:
return "phone"
case factor.Email:
return "email"
}
return "authenticator app"
}
func okData(data any) map[string]any {
m := map[string]any{"status": "ok"}
if data != nil {
m["data"] = data
}
return m
}
func errResp(msg string) map[string]any { return map[string]any{"status": "error", "msg": msg} }