Files
iam/internal/users/users.go
zeekay 30276040e1 An account, a service account and an application's org are org names, so nothing reads as Admin
The owner an account is filed under is orgs[0] of every token it is ever
issued, the org platform authority is decided on. users.Create held the
username to a rule and the owner to none, so a SuperAdmin's create stored
Admin/<name> and ac/me/<name>: accounts in orgs that do not exist, the
first of which a case-folding reader took for the reserved org. The org
name rule moves to schema.OrgName and every write that files a principal
under an org asks it; a name that is not one is refused, never lowercased.
2026-10-18 21:51:33 -07:00

770 lines
36 KiB
Go

// Copyright 2026 Hanzo AI, Inc.
// SPDX-License-Identifier: MIT OR Apache-2.0
// Package users registers the Phase-1 typed CRUD surface for the IAM v2 user
// entity on a zip App, backed by hanzoai/orm. Every operation is owner-scoped
// by the (owner, name) natural key.
//
// This is the authentication entity, so the credential invariant is absolute:
// the plaintext password rides in on the create/update request, is hashed with argon2id exactly once, and is discarded. Only the one-way digest reaches the
// store, and no response ever carries the digest or any other secret material —
// every user returned here passes through schema.User.Mask() (internal/schema/
// mask.go), the single redaction contract every read path shares.
package users
import (
"context"
"strings"
"sync"
"time"
"github.com/google/uuid"
policy "github.com/hanzoai/authz"
"github.com/hanzoai/orm"
"github.com/zap-proto/zip"
"github.com/hanzoai/iam/internal/cred"
"github.com/hanzoai/iam/internal/mfa/factor"
"github.com/hanzoai/iam/internal/principal"
"github.com/hanzoai/iam/pkg/schema"
"github.com/hanzoai/iam/pkg/store"
)
// API binds the user handlers to an orm store. Construct once at boot and register.
type API struct{ db orm.DB }
// New returns a user API over db — the constructor the native handlers (e.g. the
// signup endpoint) use to reach the ONE canonical create path (Create hashes the password with argon2id exactly once and returns the redacted row), so a user
// minted at signup is byte-identical to one minted through the CRUD surface.
func New(db orm.DB) *API { return &API{db: db} }
//go:generate go run github.com/zap-proto/zip/cmd/zipdoc
// Route registers the typed user CRUD handlers on app. The method carries the
// verb and the path carries the (owner, name) key, so a URL segment addresses one
// user: zip binds path above body, and Get and Delete take that key directly. The
// same transport-agnostic handlers project to REST and MCP alike, so that identity
// is honored on every transport.
//
// Update is the exception, structurally: UpdateInput nests the record under
// `user`, and zip binds a URL segment onto a TOP-LEVEL field only — it reaches
// through embedding, not through a named struct field. A ":owner/:name" here
// would bind nothing and leave the body the sole target, which is the one thing
// the path form exists to prevent. The key travels in the body until UpdateInput
// carries it at top level.
func Route(app *zip.Group, db orm.DB) {
a := &API{db: db}
app.Post("/v1/iam/users", a.Create, zip.WithTags("users"))
app.Get("/v1/iam/users", a.List, zip.WithTags("users"))
app.Get("/v1/iam/users/:owner/:name", a.Get, zip.WithTags("users"))
app.Put("/v1/iam/users/:owner/:name", a.Update, zip.WithTags("users"))
app.Delete("/v1/iam/users/:owner/:name", a.Delete, zip.WithTags("users"))
}
// Ref identifies one user by its natural key.
type Ref struct {
Owner string `json:"owner" validate:"required"`
Name string `json:"name" validate:"required"`
}
// Lookup addresses one user for READING: always within one organization, by the
// username OR by the email address. The two are different handles on the same
// person and a caller holds whichever it was given — a console holds the
// username, and everything that adds somebody to a team holds the address they
// were typed in as.
//
// Reading is the only operation that takes an address. A write still takes the
// natural key (Ref), because an address is a mutable attribute and resolving one
// to decide WHO GETS WRITTEN puts a rename between the authorization and the
// write.
type Lookup struct {
Owner string `json:"owner" validate:"required"`
Name string `json:"name"`
Email string `json:"email"`
}
// CreateInput carries a full user profile plus a write-only plaintext password.
// Password is never persisted — it is hashed into schema.User.PasswordHash.
type CreateInput struct {
User schema.User `json:"user"`
Password string `json:"password,omitempty" url:"-"`
// Consent is the data subject's OWN answer, and it is the only way one enters
// a new account: Create drops any consent the body carried and records this
// instead. `json:"-"` keeps it off the wire, so it can be set only by an
// in-process caller — the signup screen, which is the one place the person
// answers for themselves. A request cannot reach it, which is the point: no
// caller can assert a consent on somebody else's behalf.
Consent *schema.Consent `json:"-"`
// Terms is the person's acceptance of the Terms of Service and the Acceptable
// Use Policy, off the wire for the same reason Consent is: only the code that
// watched the person accept may state it.
Terms *schema.Terms `json:"-"`
// Type and Admin are the identity CLASS — what KIND of principal this is, and
// whether it administers its org. They are off the wire for the same reason
// Consent is: a request must not be able to assert them, and here that is a
// MONEY rule, not a profile one. store.BillingAccount answers "org:<slug>" for
// a row that is either machine-typed or an admin of its home org, IAM signs
// that as the `billing_account` claim, and account.Payer honours a signed claim
// above everything else. In the shared signup org that claim names the
// platform's own balance — so a body that could state Type or IsAdmin could
// write itself a credential that spends it.
//
// The class therefore comes from the CALLER'S CODE, never the caller's JSON:
// signup states "normal-user", federation states the same, the service-account
// surface mints its own row with its own authorization, and SCIM states an
// admin bit only when the principal is a SuperAdmin. A body that carries them
// is ignored exactly as a body-supplied Id is.
Type string `json:"-"`
Admin bool `json:"-"`
// EmailVerified records that an identity provider PROVED this address. It is
// off the wire for the same reason Type and Admin are, and it states here the
// rule Update already keeps: an address is proven by the flow that verifies it
// and by nothing else. The federation broker asks this bit before it links a
// social identity onto an existing local account — it adopts a row only when
// that row's own address was proven, or when the row carries no password
// anybody could already sign in with. A body that could state the bit would
// answer that question for the broker, and a row carrying a chosen password AND
// a stated proof passes a check that exists to say no.
//
// So the proof comes from the CALLING CODE, never the caller's JSON: the
// federation broker states what its provider vouched for, and every other
// create path — password signup, SCIM, the legacy add-user verb, the embedder
// seam — records an address nobody has proven yet.
EmailVerified bool `json:"-"`
// Application names the application that REGISTERED the account — the row's
// SignupApplication. Sign-in, signup and federation read it as authority: an
// account an application registered is found by that application's org
// wherever the account now works. A body that could state it could plant a
// stranger's address as an account some application registered, and the
// stranger's own signup would be refused as taken. So it comes from the code
// that registered the account — signup and federation — and nothing else.
Application string `json:"-"`
}
// UpdateInput carries the desired user state plus an optional new plaintext
// password. An empty Password leaves the stored digest untouched.
type UpdateInput struct {
// The target rides in the URL: PUT /v1/iam/users/acme/bob updates acme/bob
// whatever the body claims, which is what keeps the authorizer honest — it
// runs on this same decoded value, so the target authorized is the target the
// URL named and a body cannot smuggle a different one past it. json:"-" keeps
// them out of the request body, so the shape a caller sends is unchanged.
Owner string `json:"-" url:"owner"`
Name string `json:"-" url:"name"`
User schema.User `json:"user"`
Password string `json:"password,omitempty" url:"-"`
// Admin raises or lowers the org-admin bit. Nil means "leave it as stored",
// which is what every profile edit means. It is off the wire (see CreateInput):
// the bit is one of the two things store.BillingAccount reads to name an org's
// pool as the payer, so stating it is a grant of spending authority and belongs
// to a caller that has checked for it — SCIM checks authz.IsSuper.
//
// There is no Type here at all. Nothing legitimately RE-CLASSES an existing
// principal: a person does not become a machine by being edited, and the one
// surface that makes machines creates its own row. So Type is always carried
// from the stored record, like Id and CreatedTime.
Admin *bool `json:"-"`
}
// AuthzTarget reports the (owner, name) this create binds — the user entity is
// the ONE input that nests its record under `user`, so its authorization target
// is in.User.Owner, not a top-level field. Create binds the same values via this
// method, so the value the authorization seam authorizes is exactly the value
// written (internal/authz reads the same method through its owned interface).
//
// The name is normalized through schema.Username so the value authorized is the
// value STORED, not the spelling that arrived: authorizing "Alice" and then
// writing "alice" would put the authorization one principal away from the write.
// An unusable name keeps its raw spelling here and is refused by Create — a name
// that cannot be stored must not become a target that was silently approved.
func (in *CreateInput) AuthzTarget() (owner, name string) {
owner = strings.TrimSpace(in.User.Owner)
if name, err := schema.Username(in.User.Name); err == nil {
return owner, name
}
return owner, strings.TrimSpace(in.User.Name)
}
// AuthzTarget reports the (owner, name) this update binds, from the nested record
// — the same values Update writes, so authorization and execution never diverge.
func (in *UpdateInput) AuthzTarget() (owner, name string) {
// The URL wins. The body's copy is descriptive — it is what the caller says
// the record IS, not which record is being written — so it is only consulted
// where the address supplied nothing.
owner, name = strings.TrimSpace(in.Owner), strings.TrimSpace(in.Name)
if owner == "" {
owner = strings.TrimSpace(in.User.Owner)
}
if name == "" {
name = strings.TrimSpace(in.User.Name)
}
return owner, name
}
// ListInput is a paged listing request. Owner names the organization to read;
// omitting it means "the one my credential is scoped to", which for a caller
// that spans tenants is all of them. principal.Scope turns the two into one
// answer, so the field cannot be required here — requiring it would refuse the
// tenant-spanning caller before the handler could resolve anything.
type ListInput struct {
Owner string `json:"owner,omitempty"`
// Email narrows the page to the accounts carrying one address. Looking a
// person up by their address is a QUERY over the collection, not an item
// read: an address is not the natural key, two rows in one org can carry
// one, and a caller that gets a page SEES both — where a single-item read
// would have to choose, and choosing is how somebody joins a team under a
// colleague's identity.
Email string `json:"email,omitempty"`
Limit int `json:"limit,omitempty"`
Offset int `json:"offset,omitempty"`
}
// ListOutput is a page of redacted users plus the owner-scoped total.
type ListOutput struct {
Users []*schema.User `json:"users"`
Total int `json:"total"`
}
// DeleteOutput reports the outcome of a delete.
type DeleteOutput struct {
Deleted bool `json:"deleted"`
}
// Create adds a person to your organization. Send a password and it becomes the
// one they sign in with; it is hashed before it is stored and never comes back
// in any response.
//
// The username is checked against the same rule every account in the Hanzo Cloud
// is held to, whichever way it was created — this call, password signup, a social
// sign-in, or SCIM — so a name accepted here works everywhere.
//
// A name already taken in your organization is refused rather than overwritten.
func (a *API) Create(ctx context.Context, in *CreateInput) (*schema.User, error) {
owner, _ := in.AuthzTarget()
if owner == "" {
return nil, zip.ErrBadRequest("owner and name are required")
}
// THE org rule, at the same one write. The owner becomes orgs[0] of every token
// this account is ever issued — the org platform authority is decided on — so
// it is an org name or nothing: "Admin" is refused, never folded onto admin.
if err := schema.OrgName(owner); err != nil {
return nil, zip.ErrBadRequest(err.Error())
}
// THE username rule, at the ONE write every create path reaches: password
// signup, social federation, SCIM, the legacy add-user verb, the typed CRUD
// create and the embedder seam all land here. Stating it at the start of each of
// those instead left six of them stating nothing, and whatever bytes arrived
// became a principal.
name, err := schema.Username(in.User.Name)
if err != nil {
return nil, zip.ErrBadRequest(err.Error())
}
existing, err := a.lookup(ctx, owner, name)
if err != nil {
return nil, zip.ErrInternal(err.Error())
}
if existing != nil {
return nil, zip.ErrConflict("user " + owner + "/" + name + " already exists")
}
u := &in.User
u.Owner, u.Name = owner, name
// THE email rule, at the same one write, for the same reason: an address is a
// sign-in identifier too, and store.GetUserByEmail compares the canonical form.
// A row written in any other spelling is a row nobody can sign in to by address.
u.Email = store.NormalizeEmail(u.Email)
// The stable opaque identity (the OIDC `sub`) is ALWAYS minted server-side; a
// client-supplied Id is DISCARDED. Id keys the token `sub` AND the authz
// principal, so a caller allowed to PIN it could set it to a victim's UUID and,
// once two rows shared it, be resolved AS the victim (tenant-admin → SuperAdmin
// impersonation). A migrated user's legacy UUID enters through the migrator's
// direct write, never this create path.
u.Id = uuid.NewString()
// The identity class is stated by the calling CODE or it is not stated at all;
// whatever the body carried is discarded here, exactly like the Id above and
// for a closely related reason. Both are fields a caller with user-admin scope
// could otherwise point at something it was never granted — Id at a victim's
// subject, Type/IsAdmin at the org pool's `billing_account` claim.
u.Type, u.IsAdmin = in.Type, in.Admin
// The address proof is the calling code's to state as well, and whatever the
// body carried is discarded, for the reason CreateInput.EmailVerified gives:
// this bit is what the federation broker reads to decide whether a social
// identity may be linked onto an existing account, so a body that states it
// answers the broker's question on the sender's behalf. Update carries the
// stored value for the same reason.
u.EmailVerified = in.EmailVerified
// The registration is the calling code's to state for the same reason (see
// CreateInput.Application).
u.SignupApplication = in.Application
// The JSON-document store hangs no per-field DB UNIQUE constraint (the same reason
// clientId uniqueness is enforced at the write, not by an index), so reject the
// astronomically-unlikely UUID clash HERE rather than admit a second row under one
// subject. store.GetUserById also fails closed on a duplicate, so any slip is
// caught again at read.
if existing, err := store.GetUserById(ctx, a.db, u.Id); err != nil {
return nil, zip.ErrInternal(err.Error())
} else if existing != nil {
return nil, zip.ErrConflict("user id collision; retry")
}
// Never trust a client-supplied digest; the hash is derived here or nowhere.
u.PasswordHash, u.PasswordSalt = "", ""
u.PasswordType = ""
// Nor a client-supplied CREDENTIAL. These fields are credential material, so a
// body that carries one plants a value the sender already knows onto the new row.
// Minting is the ONLY writer — /v1/iam/users/{owner}/{name}/keys — so these are cleared here
// the same way the password digest is.
u.AccessKey, u.AccessSecret, u.AccessSecretHash = "", "", ""
// Nor a client-supplied CONSENT. A create body carries whatever properties the
// sender wrote, and the sender is whoever is provisioning the account — an org
// admin, an IdP, a migration — never the person the answer is about. So any
// consent in the body is DROPPED here, and the only way one enters a new
// account is in.Consent, which is off the wire (json:"-") and set by the
// signup screen, where the person answers for themselves. A new user with no
// answer reads as Unanswered, which refuses.
if err := u.SetConsent(in.Consent); err != nil {
return nil, zip.ErrBadRequest(err.Error())
}
if err := u.SetTerms(in.Terms); err != nil {
return nil, zip.ErrBadRequest(err.Error())
}
if in.Password != "" {
hash, err := hashPassword(in.Password)
if err != nil {
return nil, zip.ErrInternal("hash password: " + err.Error())
}
u.PasswordHash = hash
u.PasswordType = cred.TypeArgon2id
}
now := nowRFC3339()
u.CreatedTime, u.UpdatedTime = now, now
u.Init(a.db)
if err := u.Create(); err != nil {
return nil, zip.ErrInternal(err.Error())
}
return u.Mask(), nil
}
// Get returns one person in your organization, addressed by their username or by
// their email address. Passwords, API secrets and MFA material are stripped from
// the response.
//
// An address that names two accounts names none: the read refuses rather than
// picking one, and says so instead of reporting "no such user". Handing back an
// arbitrary one of two rows is how somebody gets added to a team under a
// colleague's identity.
func (a *API) Get(ctx context.Context, in *Lookup) (*schema.User, error) {
name, email := strings.TrimSpace(in.Name), strings.TrimSpace(in.Email)
if (name == "") == (email == "") {
return nil, zip.ErrBadRequest("exactly one of name or email is required")
}
u, err := a.resolve(ctx, in.Owner, name, email)
switch {
case err == store.ErrEmailAmbiguous:
return nil, zip.ErrConflict(err.Error())
case err != nil:
return nil, zip.ErrInternal(err.Error())
case u == nil:
return nil, zip.ErrNotFound("user " + in.Owner + "/" + firstOf(name, email) + " not found")
}
return u.Mask(), nil
}
// resolve reads the one user an address names within owner. Both arms go through
// store, which owns what an address IS — the username rule (case-folding, the
// legacy mixed-case fallback) and the email rule (normalization, and failing
// closed when one address names two rows). Restating either here would make this
// surface disagree with the one login authenticates against.
func (a *API) resolve(ctx context.Context, owner, name, email string) (*schema.User, error) {
if name != "" {
return a.lookup(ctx, owner, name)
}
return store.GetUserByEmail(ctx, a.db, owner, email)
}
// firstOf returns the first non-empty of two strings — which of the two handles
// the caller actually used, for the not-found message.
func firstOf(a, b string) string {
if a != "" {
return a
}
return b
}
// List returns a page of the people in an organization, with the total so you
// can page through the rest. Passwords, API secrets and MFA material are stripped
// from every entry.
//
// Which organization comes from your credentials, not from the request: you read
// your own and no one else's, and a credential whose scope spans tenants reads
// the tenant it names — or, naming none, every one of them.
func (a *API) List(ctx context.Context, in *ListInput) (*ListOutput, error) {
// principal.Scope is the whole tenant decision, and it has to be taken HERE.
// A confidential client reaches this collection on a CAPABILITY, and a
// capability names the collection rather than a tenant — so neither the Guard
// nor the op seam has an org to weigh, whether the request names another one
// or names none. The handler is the only place holding the credential and the
// query at once, so it is the only place the two become one answer.
owner, err := principal.Scope(ctx, strings.TrimSpace(in.Owner))
if err != nil {
return nil, err
}
// Both the count and the page go through the SAME narrowing, or a filtered
// read answers "1 of 40" and a caller pages forever through rows it filtered out.
narrow := func() *orm.ModelQuery[schema.User] {
q := orm.TypedQuery[schema.User](a.db)
if owner != "" {
q = q.Filter("Owner=", owner)
}
if email := strings.TrimSpace(in.Email); email != "" {
q = q.Filter("Email=", email)
}
return q
}
total, err := narrow().Count(ctx)
if err != nil {
return nil, zip.ErrInternal(err.Error())
}
q := narrow().Order("Name")
if in.Limit > 0 {
q = q.Limit(in.Limit)
}
if in.Offset > 0 {
q = q.Offset(in.Offset)
}
list, err := q.GetAll(ctx)
if err != nil {
return nil, zip.ErrInternal(err.Error())
}
for i, u := range list {
list[i] = u.Mask()
}
return &ListOutput{Users: list, Total: total}, nil
}
// Update changes a person's profile, their roles, or the credentials they sign
// in with. Send a password to reset it; leave it out and their current one keeps
// working.
//
// Who they are does not change: their organization, username and the identifier
// their existing sessions are keyed on all survive the write, so an update never
// signs anyone out.
//
// A SuperAdmin's account is changed only by a SuperAdmin.
func (a *API) Update(ctx context.Context, in *UpdateInput) (*schema.User, error) {
owner, name := in.AuthzTarget()
if owner == "" || name == "" {
return nil, zip.ErrBadRequest("owner and name are required")
}
existing, err := a.lookup(ctx, owner, name)
if err != nil {
return nil, zip.ErrInternal(err.Error())
}
if existing == nil {
return nil, zip.ErrNotFound("user " + owner + "/" + name + " not found")
}
if err := Authorize(ctx, existing.Owner); err != nil {
return nil, err
}
u := &in.User
u.Owner, u.Name = owner, name
u.Email = store.NormalizeEmail(u.Email)
// How the account signs in — its password, its address, its phone — changes
// only under Credentials.
if what := credentialChange(existing, u, in.Password); what != "" {
if err := Credentials(ctx, a.db, existing.Owner, existing.Name, what); err != nil {
return nil, err
}
}
// Preserve immutable identity and creation provenance. Id is the stable OIDC
// `sub` (and the authz principal key): like CreatedTime it is carried from the
// stored row and a body-supplied value is IGNORED — mutating it would move the
// user's subject (breaking every session/reference) or, worse, point it at a
// victim's UUID for impersonation on the money path.
u.Id = existing.Id
u.CreatedTime = existing.CreatedTime
u.UpdatedTime = nowRFC3339()
// Lockout state is SERVER-OWNED, exactly like Id/CreatedTime: recordAttempt is its
// only writer. Carry it from the stored row and IGNORE any body value — this is a
// full-row write, so an omitted (or 0) signinWrongTimes would otherwise overwrite a
// LOCKED account's counter to 0, and a routine admin profile edit would silently
// unlock a user mid-attack (F-6).
u.SigninWrongTimes = existing.SigninWrongTimes
u.LastSigninWrongTime = existing.LastSigninWrongTime
// The identity CLASS is server-owned too, and for a money reason rather than a
// bookkeeping one. Type and IsAdmin are the two facts store.BillingAccount reads
// to answer "this principal spends the ORG POOL", which IAM then signs as the
// `billing_account` claim and account.Payer honours above every other signal —
// so in the shared signup org either field is a claim on the platform's own
// balance. This is a full-row write reached by the typed CRUD update AND the
// legacy update-user verb, both of which bind a whole user from the body, so
// without this an org admin could re-class any member of its org — quietly, and
// with isAdmin left false, since machine-typing alone is enough. Type is never
// restated; IsAdmin only by a caller that has checked it may (SCIM, SuperAdmin).
u.Type = existing.Type
u.IsAdmin = existing.IsAdmin
if in.Admin != nil {
u.IsAdmin = *in.Admin
}
// EmailVerified is a PROOF the server recorded, not a property a body may state.
// It is what the federation broker asks before it links a social identity onto an
// existing local account: it adopts a row only when that row's own address was
// proven, or when the row carries no password anybody could already sign in with.
// A body that could state it would answer that question for the broker — a row
// carrying a chosen password AND a stated proof passes a gate that exists to say
// no. Signup records false, the broker records true when an identity provider
// proved it, and both write through their own paths; this one carries — and only
// for the address it was proven for. A write that changes the address leaves the
// new one unproven, or the proof of one address becomes the proof of any.
u.EmailVerified = existing.EmailVerified && u.Email == store.NormalizeEmail(existing.Email)
// The registering application is stated once, by the code that registered the
// account (CreateInput.Application), and every write after that carries it.
u.SignupApplication = existing.SignupApplication
// Every secret is carried from the stored row and any body value is IGNORED —
// the password digest, the key secret, the bearer material, the authenticator
// seed and its recovery codes. CarrySecretsFrom is the inverse of Mask, so the
// set is exactly what a reader cannot see: this is a full-row write and every
// body reaching it came from a masked read, so a stated secret is either an
// erasure (the field arrived blank) or a plant by a caller with user-admin
// scope. Each of these has its own seam — password reset below, key rotation at
// mint/revoke, multi-factor enrolment in internal/mfa.
u.CarrySecretsFrom(existing)
// AccessKey and PasswordType are READABLE, so they are not Mask's to carry — but
// they are the halves that make the carried secrets interpretable (a digest with
// no type cannot be verified; a secret with no key cannot be used), so a partial
// body must not orphan them either.
u.AccessKey = existing.AccessKey
u.PasswordType = existing.PasswordType
// A new plaintext password is the one secret a caller MAY state, through its own
// field rather than the user row.
if in.Password != "" {
hash, err := hashPassword(in.Password)
if err != nil {
return nil, zip.ErrInternal("hash password: " + err.Error())
}
u.PasswordHash = hash
u.PasswordType = cred.TypeArgon2id
u.PasswordSalt = ""
}
// Multi-factor state is carried from the stored row and any body value is IGNORED,
// the same rule as the credentials above and for a sharper version of the same
// reason. This is a full-row write, so an ordinary admin profile edit that simply
// omits these columns — which is what every partial client sends — TURNED THE
// SECOND FACTOR OFF, silently and with nothing in the audit trail saying so; and a
// body that supplies them PLANTS a factor (a TotpSecret the caller knows, a
// recovery digest they minted) on anyone in reach. factor.Copy is handed the whole
// block rather than a line per column so that "what IS multi-factor state" stays
// declared in exactly one place; the sibling SCIM surface already has the
// regression test for this (internal/scim/regression_test.go) and the native CRUD
// had none. Factors are written by internal/mfa and the login gate, through
// factor.Save, and nowhere else.
factor.Copy(u, existing)
// The consent record is the DATA SUBJECT's own answer, so it is carried from
// the stored row and a body-supplied one is IGNORED — the same rule as the
// credentials above, for the same reason: this is a full-row write that any
// org admin can perform on any member. Without it, one request both FORGES a
// grant (by sending one) and DESTROYS a real answer (by sending a body with
// no properties, which is what a partial client sends) — silently, and with
// no audit row, because nothing here knows it happened. Consent is written by
// the person it is about, at PUT /v1/iam/consent, and nowhere else.
//
// Every OTHER property still comes from the body: this carries the one record
// that is not the caller's to state, not the whole map.
if err := u.CarryConsentFrom(existing); err != nil {
return nil, zip.ErrInternal(err.Error())
}
// Terms acceptance is carried for the same reason: it is the person's own act.
if err := u.CarryTermsFrom(existing); err != nil {
return nil, zip.ErrInternal(err.Error())
}
// Retarget the decoded value at the stored row (same orm key), then update.
u.Init(a.db)
u.SetKey(existing.Key())
if err := u.Update(); err != nil {
return nil, zip.ErrInternal(err.Error())
}
return u.Mask(), nil
}
// Delete removes a person from your organization. Their sessions stop working
// immediately and the account is gone rather than suspended — to keep the record
// and only stop sign-in, update the user instead.
//
// A SuperAdmin's account is removed only by a SuperAdmin.
func (a *API) Delete(ctx context.Context, in *Ref) (*DeleteOutput, error) {
existing, err := a.lookup(ctx, in.Owner, in.Name)
if err != nil {
return nil, zip.ErrInternal(err.Error())
}
if existing == nil {
return nil, zip.ErrNotFound("user " + in.Owner + "/" + in.Name + " not found")
}
if err := Authorize(ctx, existing.Owner); err != nil {
return nil, err
}
// Take the account off every roster BEFORE removing it. The membership rows
// are what an org's member list is built from, so an account deleted while
// they remain is a person who no longer exists still listed as able to act —
// in every org they were ever added to, not only this one.
//
// Rows first, because the two orders fail differently. This way a failure
// stops the delete and answers it: nothing is gone, and a retry is clean. The
// other way the account is already gone when the cleanup fails, and there is
// no honest answer left to give — the delete succeeded and the roster is
// wrong, with no caller able to tell.
//
// A crash between the two leaves a live account holding its home org and
// missing its team rows: strictly LESS access than before, which is the
// direction to fail in, and the retry finishes the job.
if err := store.DeleteUser(ctx, a.db, existing); err != nil {
return nil, zip.ErrInternal(err.Error())
}
return &DeleteOutput{Deleted: true}, nil
}
// Authorize refuses a write to an account in the admin org unless the caller is
// a SuperAdmin. It covers everything that is theirs: the row (password, address,
// phone, profile), its deletion, its second factors, the credentials that name
// them, and the organizations they belong to.
//
// The admin org is where every SuperAdmin lives (schema.User.SuperAdmin), so this
// is the gate on a SuperAdmin's account, and it holds for the platform machines
// beside them and for a name no row holds yet: platform authority is written
// only by platform authority, and an application never holds it. It asks the
// owner as written, because resolving the name to its row folds the case of the
// name and never changes its org.
//
// The ordinary gates do not answer this. They ask who may write an org's users;
// a membership write names a USER in the admin org while authorizing the org it
// grants, so without this an org's admin could add a SuperAdmin to their org or
// take them out of it.
// Credentials is the rule for changing how ANOTHER account signs in — its
// password, its address or phone, its second factor. In an org whose name the
// platform holds (authz.IsHeldOrg: the brands, their directories, the platform's
// own names) the members are not one tenant with its admins: a customer who
// lives there is the platform's to serve, not its staff's to sign in as. So
// there only the person themselves, a SuperAdmin, or a platform application
// holding the user-administration capability (the SuperAdmin's console) changes
// them, and each such change is audited. Anywhere else an org's admin
// administers its own members as before.
//
// It is asked after Authorize and the entity check, which decide whether the
// caller may write the row at all; this decides whether that write may include
// how its owner signs in.
//
// A call with no principal is the embedding host's own, in process, and is
// trusted as Authorize trusts it.
func Credentials(ctx context.Context, db orm.DB, owner, name, what string) error {
p, ok := principal.From(ctx)
if !ok {
return nil
}
if p.App == nil && !p.Machine && p.Org == owner && strings.EqualFold(p.User, name) {
return nil
}
if !policy.IsHeldOrg(owner) {
return nil
}
if (p.Sudo && p.App == nil) || p.App != nil {
by := p.Org + "/" + p.User
if p.App != nil {
by = "app:" + p.App.Owner + "/" + p.App.Name
}
store.Record(ctx, db, &schema.AuditLog{
Owner: owner, Organization: owner, User: owner + "/" + name,
Action: schema.ActionSuperAdmin, Object: "credentials:" + what + " by " + by,
Method: "PUT", StatusCode: 200,
})
return nil
}
return zip.ErrForbidden("in " + owner + " only the person or a SuperAdmin changes how an account signs in")
}
func Authorize(ctx context.Context, owner string) error {
if p, ok := principal.From(ctx); ok && p.Sudo && p.App == nil {
return nil
}
if owner == policy.AdminOrg {
return zip.ErrForbidden("only a SuperAdmin may change an account in the admin organization")
}
return nil
}
// lookup resolves a single user by its (owner, name) natural key. It returns
// (nil, nil) when no row matches — a not-found is not an error here.
//
// It goes through store.GetUserByName rather than repeating the query, so this
// entity's own CRUD resolves a name exactly the way login, token minting and the
// subject decoder do. Restating it here is how Create's uniqueness check came to
// be case-SENSITIVE while the rule it guards is not — it would have admitted an
// "Alice" alongside an existing "alice" and called them different people.
func (a *API) lookup(ctx context.Context, owner, name string) (*schema.User, error) {
return store.GetUserByName(ctx, a.db, owner, name)
}
// hashPassword derives a one-way argon2id digest (SOTA) via the ONE cred.Hash —
// the single place password hashing lives, so every mint is the same strong scheme.
func hashPassword(plaintext string) (string, error) {
return cred.Hash(plaintext)
}
// VerifyPassword reports whether plaintext matches the user's stored digest,
// resolving the hash algorithm FROM THE ROW (never a constant).
//
// orgPasswordType is the owning organization's PasswordType, used as the
// fallback when the user row carries none — the same resolution v1 does
// (object/check.go: user.PasswordType → organization.PasswordType → dispatch).
// This matters at cutover: every live v1 row is argon2id, and a bcrypt-only
// verifier handed an argon2id PHC digest fails EVERY real login. Fails closed on
// an unknown/unsupported scheme (see internal/cred).
//
// It is the single verify choke point for the login path — the digest itself
// never leaves the store, so verification happens here, against the row.
//
// No account, or an account with no password, still pays one verify against a
// digest nobody holds, so a refusal takes as long as a wrong password does and its
// timing says neither whether the identifier names anybody nor whether that
// account has a password.
func VerifyPassword(u *schema.User, plaintext, orgPasswordType string) bool {
if u == nil || u.PasswordHash == "" {
if h := decoy(); h != "" {
_ = cred.Verify(cred.TypeArgon2id, plaintext, h)
}
return false
}
return cred.Verify(cred.Resolve(u.PasswordType, orgPasswordType), plaintext, u.PasswordHash)
}
// decoy is a password digest no one holds, minted once at the current parameters.
var decoy = sync.OnceValue(func() string {
h, _ := cred.Hash("decoy")
return h
})
// nowRFC3339 is the single timestamp format for v1-compatible string times.
func nowRFC3339() string { return time.Now().UTC().Format(time.RFC3339) }
// credentialChange names what of an account's sign-in a write changes — "" when
// none. A full-row write that leaves the address or phone out erases it, and an
// erasure is a change.
func credentialChange(existing, next *schema.User, password string) string {
var what []string
if password != "" {
what = append(what, "password")
}
if store.NormalizeEmail(next.Email) != store.NormalizeEmail(existing.Email) {
what = append(what, "email")
}
if store.NormalizePhone(next.Phone) != store.NormalizePhone(existing.Phone) {
what = append(what, "phone")
}
return strings.Join(what, ",")
}