contracts

type Deactivated struct {
	UserID uuid.UUID `json:"userId"`
	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 PasswordSet struct {
	UserID uuid.UUID `json:"userId"`
	At     time.Time `json:"at"`
}

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 {
	// 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 and makes the user active. 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 `` /* 164-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"`
}