Files
iam/internal/users/zipdoc_gen.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

96 lines
25 KiB
Go

// Code generated by zipdoc; DO NOT EDIT.
package users
import (
"github.com/zap-proto/zip"
)
func init() {
zip.Describe("github.com/hanzoai/iam/internal/users DELETE /v1/iam/users/:owner/:name", zip.Doc{
Description: "Removes a person from your organization. Their sessions stop working\nimmediately and the account is gone rather than suspended — to keep the record\nand only stop sign-in, update the user instead.\n\nA SuperAdmin's account is removed only by a SuperAdmin, and only a SuperAdmin\nremoves the last admin of an organization. Every token the account holds stops\nworking at once.",
})
zip.Describe("github.com/hanzoai/iam/internal/users GET /v1/iam/users", zip.Doc{
Description: "Returns a page of the people in an organization, with the total so you\ncan page through the rest. Passwords, API secrets and MFA material are stripped\nfrom every entry.\n\nWhich organization comes from your credentials, not from the request: you read\nyour own and no one else's, and a credential whose scope spans tenants reads\nthe tenant it names — or, naming none, every one of them.",
Fields: map[string]string{
"ListInput.email": "Email narrows the page to the accounts carrying one address. Looking a\nperson up by their address is a QUERY over the collection, not an item\nread: an address is not the natural key, two rows in one org can carry\none, and a caller that gets a page SEES both — where a single-item read\nwould have to choose, and choosing is how somebody joins a team under a\ncolleague's identity.",
"ListInput.isAdmin": "IsAdmin narrows the page to the org's admins: the accounts that live in it\nwith the org-admin flag. Admins by membership are on the org's roster,\nGET /v1/iam/memberships?org=, with role admin or owner. The SuperAdmins are\nthe people of the admin org, GET /v1/iam/users?owner=admin, which only a\nSuperAdmin reads.",
"Model[github.com/hanzoai/iam/pkg/schema.User].id": "Persisted fields",
"User.accessKey": "API credentials. AccessSecret / AccessSecretHash / the OAuth tokens are\nbearer material, so Mask blanks them and the handler's redact() strips them\nbefore responding. They carry real json tags because a field orm never saves\nis a field that silently vanishes.\n\nA presented secret is resolved through Key.AccessSecretDigest and nowhere\nelse, so no credential is ISSUED into these columns: they hold what older\nrows left behind, and every writer that touches them clears them.",
"User.balance": "Balance mirrors v1 for lossless migration but is authoritative in\nCommerce (billing.hanzo.ai), not here — do not write it from IAM.",
"User.createdIp": "Sign-in provenance.",
"User.displayName": "Profile.",
"User.epoch": "Epoch voids every token issued to this account at or before it (Unix\nseconds). store.Void sets it when the account loses authority — demoted\nfrom org admin, or removed from an org — so a token that still carries the\nold claims stops working at once rather than at its expiry. Voids is the\none predicate; the server owns the value and no request states it.",
"User.github": "Linked federated-identity subjects, one column per connector (v1 parity).",
"User.id": "Id is the user's STABLE OPAQUE identifier — the value the OIDC `sub` claim\ncarries. It is the v1 the legacy surface per-row UUID (e.g.\n\"e7d7fda0-4c53-4508-9d35-7ec892b7e5d7\"), migrated verbatim so a user's `sub`\nis byte-identical across the cutover: every live session, external reference,\nand the downstream money-path principal keyed on `sub` survive unchanged. A\nuser minted natively in v2 is assigned a fresh UUID here on create, so the\n`sub` is ALWAYS a stable opaque id going forward — never the (Owner, Name)\npair, which is mutable (a rename would otherwise silently reissue identity).\n\nIt is distinct from the embedded orm.Model STORAGE KEY — the value the datastore\nlocks and looks a row up by — which is NOT (Owner, Name) for every row: a MIGRATED\nlegacy row is stamped \"owner/name\" (SetId in the migrator), but a v2-native\nusers.Create'd row is NOT — Create allocates rather than pinning a key, so its\nstorage key is a store-assigned surrogate id (a decimal string like\n\"17847909129933610000001\"). (Owner, Name) is therefore the natural/QUERY key\n(unique, indexed), not necessarily the storage key: resolve a row for a locked\nwrite by its REAL key (store.GetUserByName(...).Key().Encode(), which stamps both\nshapes — see internal/oidc updateUser), never by assuming \"owner/name\". This Id is\na first-class, indexed DOMAIN field; its json tag \"id\" dominates the promoted\norm.Model `Id_` (also \"id\") by shallower depth, so the persisted record's \"id\" is\nthis UUID — exactly the v1 shape. A row that carries no Id (a not-yet-assigned\npre-cutover user) falls back to the (Owner, Name) subject at mint; every other\npath resolves `sub`→user by Id.",
"User.isAdmin": "IsAdmin is the org-admin flag: this account administers its own org (Owner).\nIt is NEVER platform authority (that is SuperAdmin, below). It is always\nwritten out, false included, so a reader can tell \"not an admin\" from \"not\nsaid\"; who may move it is users.Admin, and every move is an audit row.",
"User.isDefaultAvatar": "State flags.",
"User.mfaRememberDigest": "MfaRememberDigest is the digest of the token held by the ONE browser the\ndeadline above applies to. Without it the deadline is account-wide and \"don't\nask again on this browser\" switches the second factor off everywhere. It is a\ndigest, never the token, so a database dump yields nothing presentable — and it\ncarries a REAL json tag because orm persists via json.Marshal, so `json:\"-\"`\nwould never be stored (the trap PasswordHash documents above); Mask() strips it\nfrom every response instead.",
"User.nameKey": "NameKey is Fold(Name), derived on every save (BeforeCreate, BeforeUpdate) and\non every open for a row saved without it (store.Prepare): the indexed key a\ncase-insensitive username lookup reads (store.GetUserByName). It is always\nwritten, empty or not, so a row that has been keyed is never mistaken for one\nthat has not.",
"User.owner": "Identity / tenancy. (Owner, Name) is the natural key.",
"User.passwordHash": "Credential material. PasswordHash is a one-way bcrypt digest and is\nverify-only. It MUST be persisted (orm serializes the entity to its JSON\ndata column, so a json:\"-\" field would never be stored — that silently\nbroke login), so it carries a real json tag; the users API redact() strips\nit (and every other secret) from every response. PasswordType and\nPasswordSalt describe the digest scheme so rows hashed under the legacy\nargon2id scheme can still be verified and lazily re-hashed to bcrypt.",
"User.webauthnCredentials": "Multi-factor authentication. TotpSecret and RecoveryCodes are secret\nverify-only material — the handler strips them from every response.\nWebauthnCredentials is carried as raw JSON here for lossless migration;\nthe typed passkey model is the sibling WebauthnCredential entity.",
},
})
zip.Describe("github.com/hanzoai/iam/internal/users GET /v1/iam/users/:owner/:name", zip.Doc{
Description: "Returns one person in your organization, addressed by their username or by\ntheir email address. Passwords, API secrets and MFA material are stripped from\nthe response.\n\nAn address that names two accounts names none: the read refuses rather than\npicking one, and says so instead of reporting \"no such user\". Handing back an\narbitrary one of two rows is how somebody gets added to a team under a\ncolleague's identity.",
Fields: map[string]string{
"Model[github.com/hanzoai/iam/pkg/schema.User].id": "Persisted fields",
"User.accessKey": "API credentials. AccessSecret / AccessSecretHash / the OAuth tokens are\nbearer material, so Mask blanks them and the handler's redact() strips them\nbefore responding. They carry real json tags because a field orm never saves\nis a field that silently vanishes.\n\nA presented secret is resolved through Key.AccessSecretDigest and nowhere\nelse, so no credential is ISSUED into these columns: they hold what older\nrows left behind, and every writer that touches them clears them.",
"User.balance": "Balance mirrors v1 for lossless migration but is authoritative in\nCommerce (billing.hanzo.ai), not here — do not write it from IAM.",
"User.createdIp": "Sign-in provenance.",
"User.displayName": "Profile.",
"User.epoch": "Epoch voids every token issued to this account at or before it (Unix\nseconds). store.Void sets it when the account loses authority — demoted\nfrom org admin, or removed from an org — so a token that still carries the\nold claims stops working at once rather than at its expiry. Voids is the\none predicate; the server owns the value and no request states it.",
"User.github": "Linked federated-identity subjects, one column per connector (v1 parity).",
"User.id": "Id is the user's STABLE OPAQUE identifier — the value the OIDC `sub` claim\ncarries. It is the v1 the legacy surface per-row UUID (e.g.\n\"e7d7fda0-4c53-4508-9d35-7ec892b7e5d7\"), migrated verbatim so a user's `sub`\nis byte-identical across the cutover: every live session, external reference,\nand the downstream money-path principal keyed on `sub` survive unchanged. A\nuser minted natively in v2 is assigned a fresh UUID here on create, so the\n`sub` is ALWAYS a stable opaque id going forward — never the (Owner, Name)\npair, which is mutable (a rename would otherwise silently reissue identity).\n\nIt is distinct from the embedded orm.Model STORAGE KEY — the value the datastore\nlocks and looks a row up by — which is NOT (Owner, Name) for every row: a MIGRATED\nlegacy row is stamped \"owner/name\" (SetId in the migrator), but a v2-native\nusers.Create'd row is NOT — Create allocates rather than pinning a key, so its\nstorage key is a store-assigned surrogate id (a decimal string like\n\"17847909129933610000001\"). (Owner, Name) is therefore the natural/QUERY key\n(unique, indexed), not necessarily the storage key: resolve a row for a locked\nwrite by its REAL key (store.GetUserByName(...).Key().Encode(), which stamps both\nshapes — see internal/oidc updateUser), never by assuming \"owner/name\". This Id is\na first-class, indexed DOMAIN field; its json tag \"id\" dominates the promoted\norm.Model `Id_` (also \"id\") by shallower depth, so the persisted record's \"id\" is\nthis UUID — exactly the v1 shape. A row that carries no Id (a not-yet-assigned\npre-cutover user) falls back to the (Owner, Name) subject at mint; every other\npath resolves `sub`→user by Id.",
"User.isAdmin": "IsAdmin is the org-admin flag: this account administers its own org (Owner).\nIt is NEVER platform authority (that is SuperAdmin, below). It is always\nwritten out, false included, so a reader can tell \"not an admin\" from \"not\nsaid\"; who may move it is users.Admin, and every move is an audit row.",
"User.isDefaultAvatar": "State flags.",
"User.mfaRememberDigest": "MfaRememberDigest is the digest of the token held by the ONE browser the\ndeadline above applies to. Without it the deadline is account-wide and \"don't\nask again on this browser\" switches the second factor off everywhere. It is a\ndigest, never the token, so a database dump yields nothing presentable — and it\ncarries a REAL json tag because orm persists via json.Marshal, so `json:\"-\"`\nwould never be stored (the trap PasswordHash documents above); Mask() strips it\nfrom every response instead.",
"User.nameKey": "NameKey is Fold(Name), derived on every save (BeforeCreate, BeforeUpdate) and\non every open for a row saved without it (store.Prepare): the indexed key a\ncase-insensitive username lookup reads (store.GetUserByName). It is always\nwritten, empty or not, so a row that has been keyed is never mistaken for one\nthat has not.",
"User.owner": "Identity / tenancy. (Owner, Name) is the natural key.",
"User.passwordHash": "Credential material. PasswordHash is a one-way bcrypt digest and is\nverify-only. It MUST be persisted (orm serializes the entity to its JSON\ndata column, so a json:\"-\" field would never be stored — that silently\nbroke login), so it carries a real json tag; the users API redact() strips\nit (and every other secret) from every response. PasswordType and\nPasswordSalt describe the digest scheme so rows hashed under the legacy\nargon2id scheme can still be verified and lazily re-hashed to bcrypt.",
"User.webauthnCredentials": "Multi-factor authentication. TotpSecret and RecoveryCodes are secret\nverify-only material — the handler strips them from every response.\nWebauthnCredentials is carried as raw JSON here for lossless migration;\nthe typed passkey model is the sibling WebauthnCredential entity.",
},
})
zip.Describe("github.com/hanzoai/iam/internal/users POST /v1/iam/users", zip.Doc{
Description: "Adds a person to your organization. Send a password and it becomes the\none they sign in with; it is hashed before it is stored and never comes back\nin any response.\n\nThe username is checked against the same rule every account in the Hanzo Cloud\nis held to, whichever way it was created — this call, password signup, a social\nsign-in, or SCIM — so a name accepted here works everywhere.\n\nA name already taken in your organization is refused rather than overwritten.\n\nSend `isAdmin: true` to create them as an admin of their organization. A\nSuperAdmin may do that in any organization; an organization's admin may in\ntheir own, unless the platform runs it (a brand), where only a SuperAdmin may.\nAnyone else is refused, never ignored. The answer states `isAdmin` as stored.",
Fields: map[string]string{
"Model[github.com/hanzoai/iam/pkg/schema.User].id": "Persisted fields",
"User.accessKey": "API credentials. AccessSecret / AccessSecretHash / the OAuth tokens are\nbearer material, so Mask blanks them and the handler's redact() strips them\nbefore responding. They carry real json tags because a field orm never saves\nis a field that silently vanishes.\n\nA presented secret is resolved through Key.AccessSecretDigest and nowhere\nelse, so no credential is ISSUED into these columns: they hold what older\nrows left behind, and every writer that touches them clears them.",
"User.balance": "Balance mirrors v1 for lossless migration but is authoritative in\nCommerce (billing.hanzo.ai), not here — do not write it from IAM.",
"User.createdIp": "Sign-in provenance.",
"User.displayName": "Profile.",
"User.epoch": "Epoch voids every token issued to this account at or before it (Unix\nseconds). store.Void sets it when the account loses authority — demoted\nfrom org admin, or removed from an org — so a token that still carries the\nold claims stops working at once rather than at its expiry. Voids is the\none predicate; the server owns the value and no request states it.",
"User.github": "Linked federated-identity subjects, one column per connector (v1 parity).",
"User.id": "Id is the user's STABLE OPAQUE identifier — the value the OIDC `sub` claim\ncarries. It is the v1 the legacy surface per-row UUID (e.g.\n\"e7d7fda0-4c53-4508-9d35-7ec892b7e5d7\"), migrated verbatim so a user's `sub`\nis byte-identical across the cutover: every live session, external reference,\nand the downstream money-path principal keyed on `sub` survive unchanged. A\nuser minted natively in v2 is assigned a fresh UUID here on create, so the\n`sub` is ALWAYS a stable opaque id going forward — never the (Owner, Name)\npair, which is mutable (a rename would otherwise silently reissue identity).\n\nIt is distinct from the embedded orm.Model STORAGE KEY — the value the datastore\nlocks and looks a row up by — which is NOT (Owner, Name) for every row: a MIGRATED\nlegacy row is stamped \"owner/name\" (SetId in the migrator), but a v2-native\nusers.Create'd row is NOT — Create allocates rather than pinning a key, so its\nstorage key is a store-assigned surrogate id (a decimal string like\n\"17847909129933610000001\"). (Owner, Name) is therefore the natural/QUERY key\n(unique, indexed), not necessarily the storage key: resolve a row for a locked\nwrite by its REAL key (store.GetUserByName(...).Key().Encode(), which stamps both\nshapes — see internal/oidc updateUser), never by assuming \"owner/name\". This Id is\na first-class, indexed DOMAIN field; its json tag \"id\" dominates the promoted\norm.Model `Id_` (also \"id\") by shallower depth, so the persisted record's \"id\" is\nthis UUID — exactly the v1 shape. A row that carries no Id (a not-yet-assigned\npre-cutover user) falls back to the (Owner, Name) subject at mint; every other\npath resolves `sub`→user by Id.",
"User.isAdmin": "IsAdmin is the org-admin flag: this account administers its own org (Owner).\nIt is NEVER platform authority (that is SuperAdmin, below). It is always\nwritten out, false included, so a reader can tell \"not an admin\" from \"not\nsaid\"; who may move it is users.Admin, and every move is an audit row.",
"User.isDefaultAvatar": "State flags.",
"User.mfaRememberDigest": "MfaRememberDigest is the digest of the token held by the ONE browser the\ndeadline above applies to. Without it the deadline is account-wide and \"don't\nask again on this browser\" switches the second factor off everywhere. It is a\ndigest, never the token, so a database dump yields nothing presentable — and it\ncarries a REAL json tag because orm persists via json.Marshal, so `json:\"-\"`\nwould never be stored (the trap PasswordHash documents above); Mask() strips it\nfrom every response instead.",
"User.nameKey": "NameKey is Fold(Name), derived on every save (BeforeCreate, BeforeUpdate) and\non every open for a row saved without it (store.Prepare): the indexed key a\ncase-insensitive username lookup reads (store.GetUserByName). It is always\nwritten, empty or not, so a row that has been keyed is never mistaken for one\nthat has not.",
"User.owner": "Identity / tenancy. (Owner, Name) is the natural key.",
"User.passwordHash": "Credential material. PasswordHash is a one-way bcrypt digest and is\nverify-only. It MUST be persisted (orm serializes the entity to its JSON\ndata column, so a json:\"-\" field would never be stored — that silently\nbroke login), so it carries a real json tag; the users API redact() strips\nit (and every other secret) from every response. PasswordType and\nPasswordSalt describe the digest scheme so rows hashed under the legacy\nargon2id scheme can still be verified and lazily re-hashed to bcrypt.",
"User.webauthnCredentials": "Multi-factor authentication. TotpSecret and RecoveryCodes are secret\nverify-only material — the handler strips them from every response.\nWebauthnCredentials is carried as raw JSON here for lossless migration;\nthe typed passkey model is the sibling WebauthnCredential entity.",
},
})
zip.Describe("github.com/hanzoai/iam/internal/users PUT /v1/iam/users/:owner/:name", zip.Doc{
Description: "Changes a person's profile, their roles, or the credentials they sign\nin with. Send a password to reset it; leave it out and their current one keeps\nworking.\n\nWho they are does not change: their organization, username and the identifier\ntheir existing sessions are keyed on all survive the write, so an update never\nsigns anyone out.\n\nA SuperAdmin's account is changed only by a SuperAdmin.\n\nSend `isAdmin` to make them an admin of their organization or to stop them\nbeing one; leave it out and it stays as it is. A SuperAdmin may change it on\nanyone. An organization's admin may change it on the other people of their own\norganization, except that only a SuperAdmin makes an admin in an organization\nthe platform runs, nobody makes themselves one, and the last admin is not\nremoved. Anyone else is refused, never ignored. Stopping someone being an admin\nsigns them out everywhere at once: every token they hold stops working. The\nanswer states `isAdmin` as stored.",
Fields: map[string]string{
"Model[github.com/hanzoai/iam/pkg/schema.User].id": "Persisted fields",
"User.accessKey": "API credentials. AccessSecret / AccessSecretHash / the OAuth tokens are\nbearer material, so Mask blanks them and the handler's redact() strips them\nbefore responding. They carry real json tags because a field orm never saves\nis a field that silently vanishes.\n\nA presented secret is resolved through Key.AccessSecretDigest and nowhere\nelse, so no credential is ISSUED into these columns: they hold what older\nrows left behind, and every writer that touches them clears them.",
"User.balance": "Balance mirrors v1 for lossless migration but is authoritative in\nCommerce (billing.hanzo.ai), not here — do not write it from IAM.",
"User.createdIp": "Sign-in provenance.",
"User.displayName": "Profile.",
"User.epoch": "Epoch voids every token issued to this account at or before it (Unix\nseconds). store.Void sets it when the account loses authority — demoted\nfrom org admin, or removed from an org — so a token that still carries the\nold claims stops working at once rather than at its expiry. Voids is the\none predicate; the server owns the value and no request states it.",
"User.github": "Linked federated-identity subjects, one column per connector (v1 parity).",
"User.id": "Id is the user's STABLE OPAQUE identifier — the value the OIDC `sub` claim\ncarries. It is the v1 the legacy surface per-row UUID (e.g.\n\"e7d7fda0-4c53-4508-9d35-7ec892b7e5d7\"), migrated verbatim so a user's `sub`\nis byte-identical across the cutover: every live session, external reference,\nand the downstream money-path principal keyed on `sub` survive unchanged. A\nuser minted natively in v2 is assigned a fresh UUID here on create, so the\n`sub` is ALWAYS a stable opaque id going forward — never the (Owner, Name)\npair, which is mutable (a rename would otherwise silently reissue identity).\n\nIt is distinct from the embedded orm.Model STORAGE KEY — the value the datastore\nlocks and looks a row up by — which is NOT (Owner, Name) for every row: a MIGRATED\nlegacy row is stamped \"owner/name\" (SetId in the migrator), but a v2-native\nusers.Create'd row is NOT — Create allocates rather than pinning a key, so its\nstorage key is a store-assigned surrogate id (a decimal string like\n\"17847909129933610000001\"). (Owner, Name) is therefore the natural/QUERY key\n(unique, indexed), not necessarily the storage key: resolve a row for a locked\nwrite by its REAL key (store.GetUserByName(...).Key().Encode(), which stamps both\nshapes — see internal/oidc updateUser), never by assuming \"owner/name\". This Id is\na first-class, indexed DOMAIN field; its json tag \"id\" dominates the promoted\norm.Model `Id_` (also \"id\") by shallower depth, so the persisted record's \"id\" is\nthis UUID — exactly the v1 shape. A row that carries no Id (a not-yet-assigned\npre-cutover user) falls back to the (Owner, Name) subject at mint; every other\npath resolves `sub`→user by Id.",
"User.isAdmin": "IsAdmin is the org-admin flag: this account administers its own org (Owner).\nIt is NEVER platform authority (that is SuperAdmin, below). It is always\nwritten out, false included, so a reader can tell \"not an admin\" from \"not\nsaid\"; who may move it is users.Admin, and every move is an audit row.",
"User.isDefaultAvatar": "State flags.",
"User.mfaRememberDigest": "MfaRememberDigest is the digest of the token held by the ONE browser the\ndeadline above applies to. Without it the deadline is account-wide and \"don't\nask again on this browser\" switches the second factor off everywhere. It is a\ndigest, never the token, so a database dump yields nothing presentable — and it\ncarries a REAL json tag because orm persists via json.Marshal, so `json:\"-\"`\nwould never be stored (the trap PasswordHash documents above); Mask() strips it\nfrom every response instead.",
"User.nameKey": "NameKey is Fold(Name), derived on every save (BeforeCreate, BeforeUpdate) and\non every open for a row saved without it (store.Prepare): the indexed key a\ncase-insensitive username lookup reads (store.GetUserByName). It is always\nwritten, empty or not, so a row that has been keyed is never mistaken for one\nthat has not.",
"User.owner": "Identity / tenancy. (Owner, Name) is the natural key.",
"User.passwordHash": "Credential material. PasswordHash is a one-way bcrypt digest and is\nverify-only. It MUST be persisted (orm serializes the entity to its JSON\ndata column, so a json:\"-\" field would never be stored — that silently\nbroke login), so it carries a real json tag; the users API redact() strips\nit (and every other secret) from every response. PasswordType and\nPasswordSalt describe the digest scheme so rows hashed under the legacy\nargon2id scheme can still be verified and lazily re-hashed to bcrypt.",
"User.webauthnCredentials": "Multi-factor authentication. TotpSecret and RecoveryCodes are secret\nverify-only material — the handler strips them from every response.\nWebauthnCredentials is carried as raw JSON here for lossless migration;\nthe typed passkey model is the sibling WebauthnCredential entity.",
},
})
}