Files

438 lines
16 KiB
Go

// Copyright 2026 Hanzo AI, Inc.
// SPDX-License-Identifier: MIT OR Apache-2.0
// Package superadmin appoints and dismisses SuperAdmins (HIP-0527 §3 Appoint a
// SuperAdmin, R2). An appointment creates a NEW account admin/<name> for a named
// person; it never moves or promotes an existing account. The actor is a
// SuperAdmin person who signed in, in person, within StepUp — a credential minted
// for them by anyone else does not qualify. Each act and its fact are one write:
// the account row and a platform-written audit row in one transaction, on a store
// whose transactions are real.
//
// The account is created holding no credential and no org role: no password, no
// key, no membership, no admin flag (R1). Its address is the target's proven
// address, so the person sets a password by a code mailed there and nobody else
// can.
package superadmin
import (
"context"
"encoding/json"
"errors"
"log"
"strings"
"time"
"github.com/google/uuid"
policy "github.com/hanzoai/authz"
"github.com/hanzoai/orm"
"github.com/zap-proto/zip"
"github.com/hanzoai/iam/internal/httpx"
"github.com/hanzoai/iam/internal/oidc"
"github.com/hanzoai/iam/internal/principal"
"github.com/hanzoai/iam/pkg/schema"
"github.com/hanzoai/iam/pkg/store"
)
// Path is the SuperAdmin collection: POST appoints, DELETE /:name dismisses.
const Path = "/v1/iam/superadmins"
// StepUp bounds how long ago the actor must have signed in.
const StepUp = 10 * time.Minute
// person is the class a SuperAdmin account carries. A row with no class is not
// counted as one here, whatever the older predicate says of it.
const person = "normal-user"
//go:generate go run github.com/zap-proto/zip/cmd/zipdoc
// Route registers the appointment surface on the guarded group.
func Route(app *zip.Group, db orm.DB) {
app.Post(Path, grantSuperAdmin(db),
zip.WithOperationID("grantSuperAdmin"),
zip.WithStatus(201, 400, 401, 403, 404, 409, 503),
zip.WithTags("superadmins"))
app.Delete(Path+"/:name", revokeSuperAdmin(db),
zip.WithOperationID("revokeSuperAdmin"),
zip.WithStatus(204, 401, 403, 404, 409, 503),
zip.WithTags("superadmins"))
}
// Target names the person a SuperAdmin account is made for, by the natural key
// of the account they sign in with today.
type Target struct {
Owner string `json:"owner" validate:"required"`
Name string `json:"name" validate:"required"`
}
// GrantInput appoints a SuperAdmin.
type GrantInput struct {
// Target is the person the account is for.
Target Target `json:"target"`
// Name is the new account's username in the admin directory. Empty takes the
// target's own username.
Name string `json:"name,omitempty"`
Auth string `json:"-" header:"Authorization"`
}
// AuthzTarget is the account the appointment writes: admin/<name>.
func (in *GrantInput) AuthzTarget() (owner, name string) {
if in.Name != "" {
return policy.AdminOrg, in.Name
}
return policy.AdminOrg, in.Target.Name
}
// RevokeInput dismisses the SuperAdmin admin/<name>.
type RevokeInput struct {
Name string `json:"name" validate:"required"`
Auth string `json:"-" header:"Authorization"`
}
// AuthzTarget is the account the dismissal removes: admin/<name>.
func (in *RevokeInput) AuthzTarget() (owner, name string) { return policy.AdminOrg, in.Name }
// Appointed reports the account an appointment created and the person it is for.
type Appointed struct {
Owner string `json:"owner"`
Name string `json:"name"`
// Id is the new account's subject.
Id string `json:"id"`
// Person is the account of the person appointed, "<owner>/<name>".
Person string `json:"person"`
// Address is where the appointed person's recovery code goes.
Address string `json:"address"`
}
// StatusCode is 201: an appointment creates an account.
func (*Appointed) StatusCode() int { return 201 }
// Dismissed is the empty answer of a dismissal.
type Dismissed struct{}
// StatusCode is 204.
func (*Dismissed) StatusCode() int { return 204 }
// grantSuperAdmin appoints a SuperAdmin for a named person.
//
// It creates a new account in the admin directory for the person who signs in as
// target today, and records the appointment on the platform trail in the same
// write. It never moves or promotes an account: target keeps everything it had,
// and the new account holds no password, key, org role or admin flag. It takes
// the target's proven address, so the person sets a password by the code mailed
// there; the answer names the person and that address.
//
// Only a SuperAdmin appoints, presenting the access token of their own sign-in
// from the last ten minutes. A target in the admin directory, a machine, a
// suspended account, one without a proven address, a person who already holds a
// SuperAdmin account, or a name an application of the admin directory holds is
// refused.
func grantSuperAdmin(db orm.DB) zip.TypedHandler[GrantInput, Appointed] {
return func(ctx context.Context, in *GrantInput) (*Appointed, error) {
actor, client, err := present(ctx, db, in.Auth)
if err != nil {
return nil, err
}
u, t, err := appoint(ctx, db, actor, client, in.Target, in.Name)
if err != nil {
return nil, err
}
return &Appointed{Owner: u.Owner, Name: u.Name, Id: u.Id, Person: t.Owner + "/" + t.Name, Address: u.Email}, nil
}
}
// revokeSuperAdmin dismisses a SuperAdmin.
//
// The account admin/<name> is removed with its memberships, and the dismissal is
// recorded on the platform trail in the same write; its sessions stop at the next
// request that reads the account. The person's own account is untouched. Only a
// SuperAdmin dismisses, presenting the access token of their own sign-in from the
// last ten minutes, and the last SuperAdmin is not dismissed.
func revokeSuperAdmin(db orm.DB) zip.TypedHandler[RevokeInput, Dismissed] {
return func(ctx context.Context, in *RevokeInput) (*Dismissed, error) {
actor, client, err := present(ctx, db, in.Auth)
if err != nil {
return nil, err
}
if err := dismiss(ctx, db, actor, client, in.Name); err != nil {
return nil, err
}
return &Dismissed{}, nil
}
}
// present is the actor of a request: a SuperAdmin person, never an application,
// whose bearer is the access token of their own recent sign-in. It answers the
// actor as "<owner>/<name>" and the client they signed in through.
func present(ctx context.Context, db orm.DB, auth string) (string, string, error) {
p, ok := principal.From(ctx)
if !ok || p == nil || !p.Sudo || p.App != nil || p.User == "" {
return "", "", zip.ErrForbidden("only a SuperAdmin appoints or dismisses a SuperAdmin")
}
u, claims, err := oidc.SignedIn(ctx, db, httpx.BearerValue(auth), StepUp)
switch {
case errors.Is(err, oidc.ErrNotSignedIn):
return "", "", zip.ErrUnauthorized("sign in again, in person, to appoint or dismiss a SuperAdmin")
case err != nil:
return "", "", internal(err)
case u.Owner != p.Org || u.Name != p.User:
return "", "", zip.ErrForbidden("only a SuperAdmin appoints or dismisses a SuperAdmin")
}
return p.Org + "/" + p.User, claims.Azp, nil
}
// appoint is the one operation that creates an account in the admin directory.
func appoint(ctx context.Context, db orm.DB, actor, client string, target Target, name string) (*schema.User, *schema.User, error) {
if name == "" {
name = target.Name
}
name, err := schema.Username(name)
if err != nil {
return nil, nil, zip.ErrBadRequest(err.Error())
}
if !store.Atomic(db) {
return nil, nil, zip.Errorf(503, "appointing a SuperAdmin needs a store with transactions")
}
var made, t *schema.User
err = db.RunInTransaction(ctx, func(tx orm.DB) error {
if err := standing(ctx, tx, actor); err != nil {
return err
}
var err error
t, err = store.GetUserByName(ctx, tx, target.Owner, target.Name)
switch {
case err != nil:
return err
case t == nil:
return zip.ErrNotFound("no account " + target.Owner + "/" + target.Name)
case t.Owner == policy.AdminOrg:
return zip.ErrBadRequest("the target already lives in the admin directory; an appointment never moves or promotes an account")
case t.Machine():
return zip.ErrBadRequest("a SuperAdmin is a person, and the target is a machine")
case t.IsForbidden || t.IsDeleted:
return zip.ErrBadRequest("the target account is suspended")
case !t.EmailVerified || store.NormalizeEmail(t.Email) == "":
return zip.ErrBadRequest("the target has no proven address to recover the account through")
}
if held, err := store.GetUserByName(ctx, tx, policy.AdminOrg, name); err != nil {
return err
} else if held != nil {
return zip.ErrConflict("admin/" + name + " exists")
}
// A client's machine token names admin/<its application>, and a subject is
// resolved to a person before an application — so an account of that name
// would answer to the client's tokens.
if app, err := store.GetApplicationByName(ctx, tx, policy.AdminOrg, name); err != nil {
return err
} else if app != nil {
return zip.ErrConflict("an application of the admin directory is named " + name)
}
switch held, err := store.GetUserByEmail(ctx, tx, policy.AdminOrg, t.Email); {
case errors.Is(err, store.ErrEmailAmbiguous), err == nil && held != nil:
return zip.ErrConflict("the target's address already names an account in the admin directory")
case err != nil:
return err
}
u := newAdmin(tx, t, name)
if existing, err := store.GetUserById(ctx, tx, u.Id); err != nil {
return err
} else if existing != nil {
return zip.ErrConflict("subject collision; retry")
}
if err := u.CreateCtx(ctx); err != nil {
return err
}
made = u
return store.Append(ctx, tx, fact(schema.ActionSuperAdminAppoint, actor, map[string]string{
"account": u.Owner + "/" + u.Name, "sub": u.Id,
"person": t.Owner + "/" + t.Name, "personSub": t.Id,
"client": client,
}, Path, 201))
})
if err != nil {
return nil, nil, answer(err)
}
return made.Mask(), t, nil
}
// newAdmin builds the account an appointment creates. It is the only code in IAM
// that files an account under the admin directory, and appoint is its one caller
// (HIP-0527 R2).
func newAdmin(tx orm.DB, who *schema.User, name string) *schema.User {
u := orm.New[schema.User](tx)
model := u.Model
now := time.Now().UTC().Format(time.RFC3339)
u.Owner = policy.AdminOrg
u.Name = name
u.Id = uuid.NewString()
u.Type = person
u.DisplayName = who.DisplayName
u.Email = store.NormalizeEmail(who.Email)
u.EmailVerified = true
u.CreatedTime, u.UpdatedTime = now, now
u.Model = model
u.SetId(policy.AdminOrg + "/" + name)
return u
}
// dismiss removes admin/<name> and records the dismissal in one write.
func dismiss(ctx context.Context, db orm.DB, actor, client, name string) error {
if !store.Atomic(db) {
return zip.Errorf(503, "dismissing a SuperAdmin needs a store with transactions")
}
err := db.RunInTransaction(ctx, func(tx orm.DB) error {
if err := standing(ctx, tx, actor); err != nil {
return err
}
u, err := store.GetUserByName(ctx, tx, policy.AdminOrg, name)
switch {
case err != nil:
return err
case u == nil || !u.SuperAdmin():
return zip.ErrNotFound("no SuperAdmin admin/" + name)
}
if live(u) {
n, err := superadmins(ctx, tx)
if err != nil {
return err
}
if n <= 1 {
return zip.ErrConflict("the last SuperAdmin is not dismissed")
}
}
key := u.Owner + "/" + u.Name
if _, err := store.ForgetUser(ctx, tx, key); err != nil {
return err
}
if err := u.DeleteCtx(ctx); err != nil {
return err
}
return store.Append(ctx, tx, fact(schema.ActionSuperAdminDismiss, actor, map[string]string{
"account": key, "sub": u.Id, "client": client,
}, Path+"/"+u.Name, 204))
})
return answer(err)
}
// standing holds the actor to I18 at the moment of the write: a live SuperAdmin
// person of the admin directory, read from its row.
func standing(ctx context.Context, tx orm.DB, actor string) error {
owner, name, _ := strings.Cut(actor, "/")
if owner != policy.AdminOrg || name == "" {
return zip.ErrForbidden("only a SuperAdmin appoints or dismisses a SuperAdmin")
}
u, err := store.GetUserByName(ctx, tx, owner, name)
if err != nil {
return err
}
if u == nil || !live(u) {
return zip.ErrForbidden("only a SuperAdmin appoints or dismisses a SuperAdmin")
}
return nil
}
// live reports whether u is a SuperAdmin this package counts: a person of the
// admin directory who says so by class, and is neither suspended nor deleted.
func live(u *schema.User) bool {
return u.SuperAdmin() && u.Type == person && !u.IsForbidden && !u.IsDeleted
}
// superadmins counts the live SuperAdmins in the admin directory.
func superadmins(ctx context.Context, tx orm.DB) (int, error) {
us, err := orm.TypedQuery[schema.User](tx).Filter("Owner=", policy.AdminOrg).GetAll(ctx)
if err != nil && !errors.Is(err, orm.ErrNotFound) {
return 0, err
}
n := 0
for _, u := range us {
if live(u) {
n++
}
}
return n, nil
}
// fact is the platform-written audit row an appointment or a dismissal leaves,
// filed on the SuperAdmin trail.
func fact(action, actor string, object map[string]string, uri string, status int) *schema.AuditLog {
body, _ := json.Marshal(object)
return &schema.AuditLog{
Owner: policy.AdminOrg,
User: actor,
Action: action,
Object: string(body),
Method: map[int]string{201: "POST", 204: "DELETE"}[status],
RequestUri: uri,
StatusCode: status,
}
}
// Classify records the class of every person in the admin directory that carries
// none, so the SuperAdmins this package counts are the SuperAdmins there are. A
// row with no class and an address, and no credential a machine could hold — no
// password and no key — is a person, and is written "normal-user" with its fact,
// one transaction per account. Any other typeless row is left as it is and
// answered, for its owner to decide: a declared service account proves itself
// with a password, and a class written here could never be corrected by its
// declaration. Idempotent: a classed row is never touched, so every boot runs it
// and only the first changes anything. Hosts run it at boot, before serving.
func Classify(ctx context.Context, db orm.DB) (classed, left []string, err error) {
us, err := orm.TypedQuery[schema.User](db).Filter("Owner=", policy.AdminOrg).GetAll(ctx)
if err != nil && !errors.Is(err, orm.ErrNotFound) {
return nil, nil, err
}
for _, u := range us {
if u.Type != "" {
continue
}
key := u.Owner + "/" + u.Name
keys, err := orm.TypedQuery[schema.Key](db).Filter("Owner=", u.Owner).Filter("User=", key).GetAll(ctx)
if err != nil && !errors.Is(err, orm.ErrNotFound) {
return classed, left, err
}
if store.NormalizeEmail(u.Email) == "" || u.PasswordHash != "" || u.AccessKey != "" || len(keys) > 0 {
left = append(left, key)
continue
}
err = db.RunInTransaction(ctx, func(tx orm.DB) error {
row, err := store.GetUserByName(ctx, tx, u.Owner, u.Name)
if err != nil || row == nil || row.Type != "" {
return err
}
row.Type = person
row.UpdatedTime = time.Now().UTC().Format(time.RFC3339)
if err := row.UpdateCtx(ctx); err != nil {
return err
}
body, _ := json.Marshal(map[string]string{"account": key, "sub": row.Id, "from": "", "to": person})
return store.Append(ctx, tx, &schema.AuditLog{
Owner: policy.AdminOrg, User: "iam", Action: schema.ActionAccountClass,
Object: string(body), Method: "BOOT", StatusCode: 200,
})
})
if err != nil {
return classed, left, err
}
classed = append(classed, key)
}
return classed, left, nil
}
// answer passes a refusal through and hides a store failure's detail.
func answer(err error) error {
if err == nil {
return nil
}
var he *zip.HTTPError
if errors.As(err, &he) {
return err
}
return internal(err)
}
func internal(err error) error {
log.Printf("superadmin: %v", err)
return zip.ErrInternal("server_error")
}