contracts

type Deactivated struct {
	UserID uuid.UUID `json:"userId"`
	At     time.Time `json:"at"`
}

type EmailVerified struct {
	UserID uuid.UUID `json:"userId"`
	Email  string    `json:"email"`
	At     time.Time `json:"at"`
}

type Invited struct {
	UserID uuid.UUID `json:"userId"`
	Email  string    `json:"email"`
	Status string    `json:"status"`
	At     time.Time `json:"at"`
}

type PasswordRegistration struct {
	Email, DisplayName string
	Password           string `json:"-"`
	Roles              []string
}

type PasswordSet struct {
	UserID uuid.UUID `json:"userId"`
	At     time.Time `json:"at"`
}

type PendingRegistration = PasswordRegistration

type RegistrationApproved struct {
	UserID uuid.UUID `json:"userId"`
	Actor  uuid.UUID `json:"actor"`
	At     time.Time `json:"at"`
}

type RegistrationPage struct {
	Items []*User `json:"items"`
	Total int64   `json:"total"`
}

type RegistrationPending struct {
	UserID uuid.UUID `json:"userId"`
	At     time.Time `json:"at"`
}

type RegistrationUnverified struct {
	UserID uuid.UUID `json:"userId"`
	Email  string    `json:"email"`
	At     time.Time `json:"at"`
}

type Registrations interface {
	// RegisterPending creates a pending account with a password and trusted
	// roles. An existing email returns ErrRegistrationExists without changing
	// that account or aborting the transaction. Validation and hashing precede the insert on
	// every attempt; it never reads an existing account to decide its response.
	RegisterPending(context.Context, db.Tx[db.Tenant], PendingRegistration) (*User, error)
	// RegisterUnverified has the same insertion and conflict guarantees, but
	// only VerifyEmail can activate the resulting password-bearing account.
	RegisterUnverified(context.Context, db.Tx[db.Tenant], PasswordRegistration) (*User, error)
	// VerifyEmail locks the user, compares the normalized expected email with
	// the current canonical email, and activates only an unverified account
	// with a password. Wrong email or lifecycle state, including replay after
	// activation, conflicts. Credentials and roles remain unchanged.
	VerifyEmail(context.Context, db.Tx[db.Tenant], uuid.UUID, string) (*User, error)
	// PendingRegistrations lists oldest first, then by ID, with bounded offset
	// pagination. Zero limit uses the standard default; invalid bounds fail.
	PendingRegistrations(context.Context, db.Tx[db.Tenant], int, int) (RegistrationPage, error)
	// ApproveRegistration activates a pending account without changing its
	// password or roles. Already-active accounts are unchanged; invited and
	// inactive and unverified accounts conflict. Actor identifies the approver.
	ApproveRegistration(context.Context, db.Tx[db.Tenant], uuid.UUID, uuid.UUID) (*User, error)
}

type Roles []string

type RolesSet struct {
	UserID uuid.UUID `json:"userId"`
	Was    []string  `json:"was"`
	Now    []string  `json:"now"`
	At     time.Time `json:"at"`
}

type Service interface {
	Registrations
	// Invite creates a user with no password, in status invited, and publishes
	// user.invited. Inviting an address that is already here is a conflict.
	Invite(ctx context.Context, tx db.Tx[db.Tenant], email, displayName string) (*User, error)

	// SetPassword hashes and stores a password for an invited or active user.
	// Pending, unverified and inactive users conflict; setup cannot bypass activation. The
	// same password again is still a write and still an event: a person who
	// changes their password to what it already was has still done it.
	SetPassword(ctx context.Context, tx db.Tx[db.Tenant], id uuid.UUID, password string) error

	// SetRoles replaces the roles this user holds. The same set again changes
	// nothing and publishes nothing.
	SetRoles(ctx context.Context, tx db.Tx[db.Tenant], id uuid.UUID, roles []string) (*User, error)

	// Deactivate stops the user signing in. Their sessions are somebody else's
	// business: the auth module refuses a session whose user is not active, so
	// there is no list of sessions to walk here.
	Deactivate(ctx context.Context, tx db.Tx[db.Tenant], id uuid.UUID) (*User, error)

	// Get is one user of this tenant.
	Get(ctx context.Context, tx db.Tx[db.Tenant], id uuid.UUID) (*User, error)

	// ByEmail is the login lookup: the user of this tenant with that address,
	// compared without case. It is ErrNotFound for an address nobody has.
	ByEmail(ctx context.Context, tx db.Tx[db.Tenant], email string) (*User, error)

	// Provision creates a user from a cross-tenant transaction, naming the
	// tenant. An empty password makes an invited user; anything else makes an
	// active one. Either way it publishes user.invited.
	//
	// It is the control plane's door and nothing else's. Every other way a user
	// comes into being is Invite, inside the tenant's own transaction; this
	// exists because a tenant's first administrator is created from outside
	// that tenant — by the bootstrap, in the same transaction as the tenant
	// itself, and by the operator inviting one into a tenant they do not
	// otherwise have a transaction in.
	Provision(ctx context.Context, tx db.Tx[db.System], tenantID uuid.UUID, email, displayName, password string, roles []string) (*User, error)
}

type User struct {
	crud.Base

	// Email identifies the person within the tenant. It is stored as it was
	// given and compared without case, which is what the unique index in
	// migrations/000007 does too.
	Email string `` /* 186-byte string literal not displayed */
	// DisplayName is what a screen shows. It is optional: an invitation has an
	// address and nothing else.
	DisplayName string `json:"displayName,omitempty" gorm:"type:text;not null;default:''" maxLength:"200" doc:"Name to show" example:"Ada Lovelace"`

	// Status is a closed set; the enum tag is what a form renders as a select
	// and what Validate refuses a value outside.
	Status string `` /* 183-byte string literal not displayed */

	// Roles are the names of the roles this person holds. What a name grants is
	// the auth module's business, which is why this is a list of strings and
	// not a list of permissions: a role can be re-granted without touching a
	// single user row.
	Roles Roles `json:"roles" gorm:"type:text[];not null;default:'{}'" required:"false" doc:"Roles this person holds in this tenant"`

	// PasswordHash is argon2id in the PHC encoding, or empty for somebody who
	// has never set one — an invited user, or one who only signs in through an
	// identity provider. It is json:"-", so it is in no response, in no request
	// and in no generated screen.
	PasswordHash string `json:"-" gorm:"type:text"`
}