Files
iam/pkg/schema/user.go
zeekay e48704c976 users: rule who makes an org admin, and make a revoke take effect now
POST /v1/iam/users and PUT /v1/iam/users/{owner}/{name} answered 200 and
dropped user.isAdmin: the field was read from the calling code only, so a
SuperAdmin could not make hanzo/denis an admin and nothing said so.

One rule, users.Admin, now decides every change to an org-admin role: the
user create and update, SCIM, an admin membership, and an invitation that
carries the role. A SuperAdmin moves it anywhere; an org's admin moves it on
the others of a customer org; only a SuperAdmin makes an admin of a brand
(policy.IsPlatformOrg) or touches the admin org; nobody raises their own; the
last admin stays (409) unless a SuperAdmin takes them; applications, machines
and members are refused (403). The request is read for presence, so leaving
isAdmin out keeps it and a full-row write cannot demote by omission.

A revoke, a removed membership, an upsert lowering and a deleted account call
store.Void: User.Epoch moves to now, the account's token rows and sessions
are deleted, and verifyBearer refuses a token with iat <= epoch.

Invitations carry a role (member or admin), written only by who may grant it
and applied on signup and accept. GET /v1/iam/users takes isAdmin=true. Every
grant, revoke, role invitation, removal and void is an audit row under the
org, with actor, target, from, to, reason and request id.

Claude-Session: https://claude.ai/code/session_016DKtyuzxU43Gsc6Pm9vKTF
2026-11-02 12:07:57 -08:00

452 lines
22 KiB
Go

// Copyright 2026 Hanzo AI, Inc.
// SPDX-License-Identifier: MIT OR Apache-2.0
package schema
import (
"encoding/json"
"strings"
policy "github.com/hanzoai/authz"
"github.com/hanzoai/orm"
)
// User is an identity principal — the v2 form of the v1 the legacy surface `user` row,
// re-expressed on hanzoai/orm. It is the authentication entity: the only
// credential material it persists is PasswordHash (a one-way bcrypt digest,
// json:"-" so it never leaves the process) and the legacy hash metadata used
// to migrate rows minted before the bcrypt cutover. The plaintext password is
// never a field on this struct — it arrives on the create/update request,
// is hashed immediately, and is discarded.
//
// The natural/query key is (Owner, Name): Owner is the tenant/organization slug,
// Name is unique within it. The embedded orm.Model[User] supplies the storage
// key, the created/updated timestamps, and the CRUD lifecycle.
type User struct {
orm.Model[User]
// Id is the user's STABLE OPAQUE identifier — the value the OIDC `sub` claim
// carries. It is the v1 the legacy surface per-row UUID (e.g.
// "e7d7fda0-4c53-4508-9d35-7ec892b7e5d7"), migrated verbatim so a user's `sub`
// is byte-identical across the cutover: every live session, external reference,
// and the downstream money-path principal keyed on `sub` survive unchanged. A
// user minted natively in v2 is assigned a fresh UUID here on create, so the
// `sub` is ALWAYS a stable opaque id going forward — never the (Owner, Name)
// pair, which is mutable (a rename would otherwise silently reissue identity).
//
// It is distinct from the embedded orm.Model STORAGE KEY — the value the datastore
// locks and looks a row up by — which is NOT (Owner, Name) for every row: a MIGRATED
// legacy row is stamped "owner/name" (SetId in the migrator), but a v2-native
// users.Create'd row is NOT — Create allocates rather than pinning a key, so its
// storage key is a store-assigned surrogate id (a decimal string like
// "17847909129933610000001"). (Owner, Name) is therefore the natural/QUERY key
// (unique, indexed), not necessarily the storage key: resolve a row for a locked
// write by its REAL key (store.GetUserByName(...).Key().Encode(), which stamps both
// shapes — see internal/oidc updateUser), never by assuming "owner/name". This Id is
// a first-class, indexed DOMAIN field; its json tag "id" dominates the promoted
// orm.Model `Id_` (also "id") by shallower depth, so the persisted record's "id" is
// this UUID — exactly the v1 shape. A row that carries no Id (a not-yet-assigned
// pre-cutover user) falls back to the (Owner, Name) subject at mint; every other
// path resolves `sub`→user by Id.
Id string `json:"id,omitempty" orm:"index"`
// Identity / tenancy. (Owner, Name) is the natural key.
Owner string `json:"owner" orm:"index"`
Name string `json:"name" orm:"index"`
CreatedTime string `json:"createdTime"`
UpdatedTime string `json:"updatedTime"`
DeletedTime string `json:"deletedTime,omitempty"`
// NameKey is Fold(Name), derived on every save (BeforeCreate, BeforeUpdate) and
// on every open for a row saved without it (store.Prepare): the indexed key a
// case-insensitive username lookup reads (store.GetUserByName). It is always
// written, empty or not, so a row that has been keyed is never mistaken for one
// that has not.
NameKey Folded `json:"nameKey" orm:"index"`
ExternalId string `json:"externalId,omitempty" orm:"index"`
Type string `json:"type,omitempty"`
// Credential material. PasswordHash is a one-way bcrypt digest and is
// verify-only. It MUST be persisted (orm serializes the entity to its JSON
// data column, so a json:"-" field would never be stored — that silently
// broke login), so it carries a real json tag; the users API redact() strips
// it (and every other secret) from every response. PasswordType and
// PasswordSalt describe the digest scheme so rows hashed under the legacy
// argon2id scheme can still be verified and lazily re-hashed to bcrypt.
PasswordHash string `json:"passwordHash,omitempty"`
PasswordType string `json:"passwordType,omitempty"`
PasswordSalt string `json:"passwordSalt,omitempty"`
// Profile.
DisplayName string `json:"displayName,omitempty"`
FirstName string `json:"firstName,omitempty"`
LastName string `json:"lastName,omitempty"`
Avatar string `json:"avatar,omitempty"`
AvatarType string `json:"avatarType,omitempty"`
PermanentAvatar string `json:"permanentAvatar,omitempty"`
Email string `json:"email,omitempty" orm:"index"`
EmailVerified bool `json:"emailVerified,omitempty"`
Phone string `json:"phone,omitempty" orm:"index"`
CountryCode string `json:"countryCode,omitempty"`
Region string `json:"region,omitempty"`
Location string `json:"location,omitempty"`
Address []string `json:"address,omitempty"`
Addresses []*Address `json:"addresses,omitempty"`
Affiliation string `json:"affiliation,omitempty"`
Title string `json:"title,omitempty"`
IdCardType string `json:"idCardType,omitempty"`
IdCard string `json:"idCard,omitempty" orm:"index"`
RealName string `json:"realName,omitempty"`
IsVerified bool `json:"isVerified,omitempty"`
Homepage string `json:"homepage,omitempty"`
Bio string `json:"bio,omitempty"`
Tag string `json:"tag,omitempty"`
Language string `json:"language,omitempty"`
Gender string `json:"gender,omitempty"`
Birthday string `json:"birthday,omitempty"`
Education string `json:"education,omitempty"`
Score int `json:"score,omitempty"`
Karma int `json:"karma,omitempty"`
Ranking int `json:"ranking,omitempty"`
// Balance mirrors v1 for lossless migration but is authoritative in
// Commerce (billing.hanzo.ai), not here — do not write it from IAM.
Balance float64 `json:"balance,omitempty"`
BalanceCredit float64 `json:"balanceCredit,omitempty"`
Currency string `json:"currency,omitempty"`
BalanceCurrency string `json:"balanceCurrency,omitempty"`
// State flags.
IsDefaultAvatar bool `json:"isDefaultAvatar,omitempty" orm:"default:false"`
IsOnline bool `json:"isOnline,omitempty" orm:"default:false"`
// IsAdmin is the org-admin flag: this account administers its own org (Owner).
// It is NEVER platform authority (that is SuperAdmin, below). It is always
// written out, false included, so a reader can tell "not an admin" from "not
// said"; who may move it is users.Admin, and every move is an audit row.
IsAdmin bool `json:"isAdmin" orm:"default:false"`
IsForbidden bool `json:"isForbidden,omitempty" orm:"default:false"`
// Epoch voids every token issued to this account at or before it (Unix
// seconds). store.Void sets it when the account loses authority — demoted
// from org admin, or removed from an org — so a token that still carries the
// old claims stops working at once rather than at its expiry. Voids is the
// one predicate; the server owns the value and no request states it.
Epoch int64 `json:"epoch,omitempty"`
IsDeleted bool `json:"isDeleted,omitempty" orm:"default:false"`
SignupApplication string `json:"signupApplication,omitempty"`
Hash string `json:"hash,omitempty"`
PreHash string `json:"preHash,omitempty"`
RegisterType string `json:"registerType,omitempty"`
RegisterSource string `json:"registerSource,omitempty"`
// API credentials. AccessSecret / AccessSecretHash / the OAuth tokens are
// bearer material, so Mask blanks them and the handler's redact() strips them
// before responding. They carry real json tags because a field orm never saves
// is a field that silently vanishes.
//
// A presented secret is resolved through Key.AccessSecretDigest and nowhere
// else, so no credential is ISSUED into these columns: they hold what older
// rows left behind, and every writer that touches them clears them.
AccessKey string `json:"accessKey,omitempty"`
AccessSecret string `json:"accessSecret,omitempty"`
AccessSecretHash string `json:"accessSecretHash,omitempty"`
AccessToken string `json:"accessToken,omitempty"`
OriginalToken string `json:"originalToken,omitempty"`
OriginalRefreshToken string `json:"originalRefreshToken,omitempty"`
// Sign-in provenance.
CreatedIp string `json:"createdIp,omitempty"`
LastSigninTime string `json:"lastSigninTime,omitempty"`
LastSigninIp string `json:"lastSigninIp,omitempty"`
// Linked federated-identity subjects, one column per connector (v1 parity).
GitHub string `json:"github,omitempty"`
Google string `json:"google,omitempty"`
QQ string `json:"qq,omitempty"`
WeChat string `json:"wechat,omitempty"`
Facebook string `json:"facebook,omitempty"`
DingTalk string `json:"dingtalk,omitempty"`
Weibo string `json:"weibo,omitempty"`
Gitee string `json:"gitee,omitempty"`
LinkedIn string `json:"linkedin,omitempty"`
Wecom string `json:"wecom,omitempty"`
Lark string `json:"lark,omitempty"`
Gitlab string `json:"gitlab,omitempty"`
Adfs string `json:"adfs,omitempty"`
Baidu string `json:"baidu,omitempty"`
Alipay string `json:"alipay,omitempty"`
Iam string `json:"iam,omitempty"`
Infoflow string `json:"infoflow,omitempty"`
Apple string `json:"apple,omitempty"`
AzureAD string `json:"azuread,omitempty"`
AzureADB2c string `json:"azureadb2c,omitempty"`
Slack string `json:"slack,omitempty"`
Steam string `json:"steam,omitempty"`
Bilibili string `json:"bilibili,omitempty"`
Okta string `json:"okta,omitempty"`
Douyin string `json:"douyin,omitempty"`
Kwai string `json:"kwai,omitempty"`
Line string `json:"line,omitempty"`
Amazon string `json:"amazon,omitempty"`
Auth0 string `json:"auth0,omitempty"`
BattleNet string `json:"battlenet,omitempty"`
Bitbucket string `json:"bitbucket,omitempty"`
Box string `json:"box,omitempty"`
CloudFoundry string `json:"cloudfoundry,omitempty"`
Dailymotion string `json:"dailymotion,omitempty"`
Deezer string `json:"deezer,omitempty"`
DigitalOcean string `json:"digitalocean,omitempty"`
Discord string `json:"discord,omitempty"`
Dropbox string `json:"dropbox,omitempty"`
EveOnline string `json:"eveonline,omitempty"`
Fitbit string `json:"fitbit,omitempty"`
Gitea string `json:"gitea,omitempty"`
Heroku string `json:"heroku,omitempty"`
InfluxCloud string `json:"influxcloud,omitempty"`
Instagram string `json:"instagram,omitempty"`
Intercom string `json:"intercom,omitempty"`
Kakao string `json:"kakao,omitempty"`
Lastfm string `json:"lastfm,omitempty"`
Mailru string `json:"mailru,omitempty"`
Meetup string `json:"meetup,omitempty"`
MicrosoftOnline string `json:"microsoftonline,omitempty"`
Naver string `json:"naver,omitempty"`
Nextcloud string `json:"nextcloud,omitempty"`
OneDrive string `json:"onedrive,omitempty"`
Oura string `json:"oura,omitempty"`
Patreon string `json:"patreon,omitempty"`
Paypal string `json:"paypal,omitempty"`
SalesForce string `json:"salesforce,omitempty"`
Shopify string `json:"shopify,omitempty"`
Soundcloud string `json:"soundcloud,omitempty"`
Spotify string `json:"spotify,omitempty"`
Strava string `json:"strava,omitempty"`
Stripe string `json:"stripe,omitempty"`
Telegram string `json:"telegram,omitempty"`
TikTok string `json:"tiktok,omitempty"`
Tumblr string `json:"tumblr,omitempty"`
Twitch string `json:"twitch,omitempty"`
Twitter string `json:"twitter,omitempty"`
Typetalk string `json:"typetalk,omitempty"`
Uber string `json:"uber,omitempty"`
VK string `json:"vk,omitempty"`
Wepay string `json:"wepay,omitempty"`
Xero string `json:"xero,omitempty"`
Yahoo string `json:"yahoo,omitempty"`
Yammer string `json:"yammer,omitempty"`
Yandex string `json:"yandex,omitempty"`
Zoom string `json:"zoom,omitempty"`
Custom string `json:"custom,omitempty"`
Custom2 string `json:"custom2,omitempty"`
Custom3 string `json:"custom3,omitempty"`
Custom4 string `json:"custom4,omitempty"`
Custom5 string `json:"custom5,omitempty"`
Custom6 string `json:"custom6,omitempty"`
Custom7 string `json:"custom7,omitempty"`
Custom8 string `json:"custom8,omitempty"`
Custom9 string `json:"custom9,omitempty"`
Custom10 string `json:"custom10,omitempty"`
// Multi-factor authentication. TotpSecret and RecoveryCodes are secret
// verify-only material — the handler strips them from every response.
// WebauthnCredentials is carried as raw JSON here for lossless migration;
// the typed passkey model is the sibling WebauthnCredential entity.
WebauthnCredentials []json.RawMessage `json:"webauthnCredentials,omitempty"`
PreferredMfaType string `json:"preferredMfaType,omitempty"`
RecoveryCodes []string `json:"recoveryCodes,omitempty"`
TotpSecret string `json:"totpSecret,omitempty"`
VerificationCode string `json:"verificationCode,omitempty"`
MfaPhoneEnabled bool `json:"mfaPhoneEnabled,omitempty"`
MfaEmailEnabled bool `json:"mfaEmailEnabled,omitempty"`
MfaRadiusEnabled bool `json:"mfaRadiusEnabled,omitempty"`
MfaRadiusUsername string `json:"mfaRadiusUsername,omitempty"`
MfaRadiusProvider string `json:"mfaRadiusProvider,omitempty"`
MfaPushEnabled bool `json:"mfaPushEnabled,omitempty"`
MfaPushReceiver string `json:"mfaPushReceiver,omitempty"`
MfaPushProvider string `json:"mfaPushProvider,omitempty"`
MultiFactorAuths []*MfaProps `json:"multiFactorAuths,omitempty"`
Invitation string `json:"invitation,omitempty" orm:"index"`
InvitationCode string `json:"invitationCode,omitempty" orm:"index"`
FaceIds []*FaceId `json:"faceIds,omitempty"`
Cart []CartItem `json:"cart,omitempty"`
Ldap string `json:"ldap,omitempty"`
Properties map[string]string `json:"properties,omitempty"`
LastChangePasswordTime string `json:"lastChangePasswordTime,omitempty"`
LastSigninWrongTime string `json:"lastSigninWrongTime,omitempty"`
SigninWrongTimes int `json:"signinWrongTimes,omitempty"`
ManagedAccounts []ManagedAccount `json:"managedAccounts,omitempty"`
MfaAccounts []MfaAccount `json:"mfaAccounts,omitempty"`
MfaItems []*MfaItem `json:"mfaItems,omitempty"`
MfaRememberDeadline string `json:"mfaRememberDeadline,omitempty"`
// MfaRememberDigest is the digest of the token held by the ONE browser the
// deadline above applies to. Without it the deadline is account-wide and "don't
// ask again on this browser" switches the second factor off everywhere. It is a
// digest, never the token, so a database dump yields nothing presentable — and it
// carries a REAL json tag because orm persists via json.Marshal, so `json:"-"`
// would never be stored (the trap PasswordHash documents above); Mask() strips it
// from every response instead.
MfaRememberDigest string `json:"mfaRememberDigest,omitempty"`
NeedUpdatePassword bool `json:"needUpdatePassword,omitempty"`
IpWhitelist string `json:"ipWhitelist,omitempty"`
ApplicationScopes []ConsentRecord `json:"applicationScopes,omitempty"`
}
// Address is a structured postal address held on a user.
type Address struct {
Tag string `json:"tag,omitempty"`
Line1 string `json:"line1,omitempty"`
Line2 string `json:"line2,omitempty"`
City string `json:"city,omitempty"`
State string `json:"state,omitempty"`
ZipCode string `json:"zipCode,omitempty"`
Region string `json:"region,omitempty"`
}
// ManagedAccount is a credential a user delegates for a downstream application.
// Password is secret verify-only material; the handler strips it on read.
type ManagedAccount struct {
Application string `json:"application,omitempty"`
Username string `json:"username,omitempty"`
Password string `json:"-"`
SigninUrl string `json:"signinUrl,omitempty"`
}
// MfaAccount is a stored TOTP authenticator entry. SecretKey never serializes.
type MfaAccount struct {
AccountName string `json:"accountName,omitempty"`
Issuer string `json:"issuer,omitempty"`
SecretKey string `json:"-"`
Origin string `json:"origin,omitempty"`
}
// MfaProps is one configured MFA method surfaced to clients. Secret and
// RecoveryCodes are verify-only and stripped from responses.
type MfaProps struct {
Enabled bool `json:"enabled,omitempty"`
IsPreferred bool `json:"isPreferred,omitempty"`
MfaType string `json:"mfaType,omitempty"`
Secret string `json:"-"`
CountryCode string `json:"countryCode,omitempty"`
URL string `json:"url,omitempty"`
RecoveryCodes []string `json:"-"`
MfaRememberInHours int `json:"mfaRememberInHours,omitempty"`
}
// MfaItem is an organization-defined MFA requirement pinned to the user. It is
// shared with Organization (which declares the org-level requirement set).
type MfaItem struct {
Name string `json:"name,omitempty"`
Rule string `json:"rule,omitempty"`
}
// FaceId is a stored face-recognition template for passwordless sign-in.
type FaceId struct {
Name string `json:"name,omitempty"`
FaceIdData []float64 `json:"faceIdData,omitempty"`
ImageUrl string `json:"imageUrl,omitempty"`
}
// CartItem is a line item retained from v1 (billing lives in Commerce).
type CartItem struct {
Owner string `json:"owner,omitempty"`
Name string `json:"name,omitempty"`
DisplayName string `json:"displayName,omitempty"`
Price float64 `json:"price,omitempty"`
Quantity int `json:"quantity,omitempty"`
}
// ConsentRecord records the scopes a user granted a given application.
type ConsentRecord struct {
Application string `json:"application,omitempty"`
GrantedScopes []string `json:"grantedScopes,omitempty"`
}
// ServiceAccount is the User.Type IAM writes for a MACHINE identity — a
// credential with no person behind it. IAM is the authority on what its own rows
// are, so the predicate reading this field lives beside the field rather than in
// a downstream library's opinion of the string. Program below is the sibling
// shape other Hanzo services stamp for the same idea, and Machine accepts both.
const ServiceAccount = "service-account"
// Program is the other word, and it is the one a TOKEN carries: the class of a
// machine with no user row, where the registration itself IS the principal.
//
// Its wire spelling is the older of the two, and that is deliberate. A row is read
// by IAM, which knows both words; a token is read by every service that validates
// one, each pinned to its own copy of the predicate — and an earlier account
// library matches ONLY this spelling. Stating the newer word in a token would read
// as a person wherever the reader had not caught up, which is precisely the
// failure the claim exists to end. The wire takes the word everyone knows.
const Program = "application"
// Machine reports whether this row is a machine identity rather than a person.
//
// It decides WHICH LEDGER the principal spends from (store.BillingAccount): a
// machine has no person, so a personal wallet keyed on its name is one no funding
// path can name and it reads $0 forever.
func (u *User) Machine() bool {
if u == nil {
return false
}
switch strings.ToLower(strings.TrimSpace(u.Type)) {
case ServiceAccount, Program:
return true
}
return false
}
// SuperAdmin reports platform authority: this row is a PERSON whose own org — the
// owner of the row — is the reserved admin org. It is THE SuperAdmin predicate;
// every gate in IAM asks it, directly or through the Principal the Guard builds
// from this row (principal.Principal.Sudo), and nothing else answers the question.
//
// A membership of the admin org is not it. A brand org's user added to the admin
// org is an ordinary member of it; platform authority goes to named people
// provisioned IN the admin org. A per-org IsAdmin is a different, org-scoped fact
// and never answers this one.
//
// A machine is never one, whatever org it lives in: its authority is what it was
// minted for, not the platform's. The same rule reads off a token as
// authz.Claims.Sudo, whose home org is the first entry of `orgs` — the owner of
// this row (store.MemberOrgRefs) — so the row and every token minted from it agree.
//
// Liveness is not part of it: a forbidden or deleted account is refused by every
// path that authenticates one, and a gate that protects a SuperAdmin's account
// must keep protecting it while it is suspended.
func (u *User) SuperAdmin() bool {
return u != nil && u.Owner == policy.AdminOrg && !u.Machine()
}
// Voids reports whether a token this account was issued at iat (Unix seconds,
// the `iat` claim; 0 when the token states none) was voided by its Epoch. A
// token minted in the same second as the void is void too: the second is all
// iat records, and failing closed costs a sign-in made within that second.
func (u *User) Voids(iat int64) bool {
return u != nil && u.Epoch > 0 && iat <= u.Epoch
}
// Picture is how this person is drawn: the image they set, or else their
// Gravatar. It is published only where the caller already holds the address.
func (u *User) Picture() string {
if u.Avatar != "" {
return u.Avatar
}
return Gravatar(u.Email)
}
// BeforeCreate and BeforeUpdate derive NameKey from Name on every save the model
// makes, so the stored key always folds the name it is stored beside.
func (u *User) BeforeCreate() error {
u.NameKey = Folded(Fold(u.Name))
return nil
}
// BeforeUpdate is BeforeCreate for a save of an existing user.
func (u *User) BeforeUpdate(*User) error {
u.NameKey = Folded(Fold(u.Name))
return nil
}