identity

type AuthSession struct {
	// SID is the public session identifier. It is not a secret: it is already a
	// claim (`sid`) in every access token issued under it, and it is the handle a
	// revoke names.
	SID string
	// UserID is the account whose authority the session exercises.
	UserID string
	// Platform is the surface that logged in ("portal", "cli", "desktop"), a
	// label for the operator reading the session list rather than something the
	// server enforces.
	Platform string
	// AuthMethod is the proof that opened the session ("password", "login_code").
	AuthMethod string
	// CreatedAt is when the login happened.
	CreatedAt time.Time
	// LastSeenAt is the most recent time a request or refresh used the session.
	// Zero until the first touch.
	LastSeenAt time.Time
	// AbsoluteExpiresAt is the hard ceiling: past it the session is inactive no
	// matter how recently it was used.
	AbsoluteExpiresAt time.Time
}

type AuthSessionStore interface {
	// CreateSession opens a session and returns its public id, which becomes the
	// `sid` claim of the access token and the session_id of the first refresh
	// token.
	CreateSession(ctx context.Context, in NewAuthSession) (sid string, err error)

	// ActiveSession returns the session if it exists, is not revoked, and has not
	// passed its absolute expiry; otherwise ErrSessionInactive. This is the
	// per-request authority check the guard makes.
	ActiveSession(ctx context.Context, sid string, now time.Time) (AuthSession, error)

	// TouchSession records that the session was used, at most once per the store's
	// own throttle so an active session does not mean a write per request. A
	// missing or inactive session is not an error: touching something already
	// gone is a no-op.
	TouchSession(ctx context.Context, sid string, now time.Time) error

	// RevokeSession revokes one session and its refresh tokens, returning how many
	// sessions it retired (0 or 1). An unknown or already-revoked session is not
	// an error.
	RevokeSession(ctx context.Context, sid string, now time.Time) (int64, error)

	// RevokeUserSessions revokes every live session the user has, and their
	// refresh tokens, returning how many sessions it retired. This is what "sign
	// them out everywhere" and disabling an account do to the credential.
	RevokeUserSessions(ctx context.Context, userID string, now time.Time) (int64, error)

	// CountUserSessions counts the user's live sessions.
	CountUserSessions(ctx context.Context, userID string, now time.Time) (int, error)

	// ListUserSessions returns the user's live sessions as safe metadata, newest
	// first, so an administrator can revoke one device rather than all of them.
	ListUserSessions(ctx context.Context, userID string, now time.Time) ([]AuthSession, error)
}

type ExternalIdentity struct {
	// ID is the public identifier of the link, the handle an admin unlink names.
	ID     string
	UserID string
	Issuer string
	// Subject is the IdP's stable `sub` for this account.
	Subject string
	// LastSeenEmail and LastSeenName are the attributes from the most recent
	// successful sign-in, kept so Portal administration can surface drift from
	// the local account without rewriting it.
	LastSeenEmail string
	LastSeenName  string
	LastLoginAt   time.Time
	CreatedAt     time.Time
}

type ExternalIdentityStore interface {
	// IdentityBySubject returns the link for one (issuer, subject), or nil when
	// none exists. This is §5.2 rule 1.
	IdentityBySubject(ctx context.Context, issuer, subject string) (*ExternalIdentity, error)

	// IdentityByUserAndIssuer returns the account's link for one issuer, or nil.
	// It is what tells rule 3 (link an unlinked account) from rule 4 (that
	// account already has a different subject at this issuer — refuse).
	IdentityByUserAndIssuer(ctx context.Context, userID, issuer string) (*ExternalIdentity, error)

	// ListUserIdentities returns every link an account has, newest first.
	ListUserIdentities(ctx context.Context, userID string) ([]ExternalIdentity, error)

	// LinkExisting links an existing account to a subject and records the link in
	// one transaction. It returns ErrIdentityConflict if either uniqueness
	// constraint rejects the insert, so a concurrent first login cannot produce a
	// second link.
	LinkExisting(ctx context.Context, in LinkIdentity) (*ExternalIdentity, error)

	// CreateUserWithIdentity creates the account, its personal Space, the owner
	// membership, and the identity link atomically, recording the creation and
	// the link in the same transaction. It returns ErrIdentityConflict or
	// ErrEmailExists when a concurrent first login won the race.
	CreateUserWithIdentity(ctx context.Context, in ProvisionUser) (*User, *ExternalIdentity, error)

	// UnlinkIdentity deletes one link and records the deletion in one
	// transaction, only while the account is disabled. It returns
	// ErrUnlinkRequiresDisabled when the account is enabled and
	// ErrIdentityNotFound when the link is not the user's.
	UnlinkIdentity(ctx context.Context, in UnlinkIdentity) error

	// UpdateLastSeen refreshes the display attributes and last-login time after a
	// successful sign-in. It is best-effort: a missing link is not an error.
	UpdateLastSeen(ctx context.Context, issuer, subject string, seen SeenClaims, now time.Time) error
}

type LinkIdentity struct {
	UserID  string
	Issuer  string
	Subject string
	Seen    SeenClaims
}

type LoginCodeStore interface {
	// CreateLoginCode issues a single-use code for userID and returns the
	// plaintext, which is never stored and cannot be recovered afterwards.
	CreateLoginCode(ctx context.Context, userID string, ttl time.Duration) (plaintext string, expiresAt time.Time, err error)

	// ConsumeLoginCode redeems a code that was issued to userID. A code that
	// is unknown, already used, expired, or issued to somebody else returns
	// (false, nil) — the caller cannot tell which, and neither can an
	// attacker. Redemption is atomic: concurrent calls with the same code
	// produce exactly one winner.
	//
	// The account is named by the caller rather than reported back, so that a
	// code submitted with the wrong address is left untouched. A redemption
	// that spent the code first and checked the account afterwards burned it
	// on a typo, and the person retrying with the right address was then
	// refused for a reason nobody could see.
	ConsumeLoginCode(ctx context.Context, plaintext, userID string, now time.Time) (redeemed bool, err error)
}

type NewAuthSession struct {
	UserID            string
	Platform          string
	AuthMethod        string
	AbsoluteExpiresAt time.Time
}

type NewRefreshToken struct {
	UserID string
	// SessionID names one login chain. Every rotation keeps it, so revoking a
	// session retires the whole chain rather than one link of it.
	SessionID string
	// Platform records which surface logged in ("portal", "cli", "desktop").
	// It is a label for the operator reading the session list, not something
	// the server enforces.
	Platform string
	TTL      time.Duration
}

type PasswordStore interface {
	// PasswordHash returns the stored hash for userID, or "" when the account
	// has no password and can only sign in with a login code.
	PasswordHash(ctx context.Context, userID string) (string, error)
	// SetPassword stores an already-hashed password. Hashing belongs to the
	// caller — this interface must not be a place where a plaintext password
	// can be passed by mistake.
	SetPassword(ctx context.Context, userID, encodedHash string, setAt time.Time) error
}

type ProvisionUser struct {
	Email     string
	Name      string
	QuotaTier string
	Issuer    string
	Subject   string
}

type RefreshTokenStore interface {
	// CreateRefreshToken issues a token and returns the plaintext, which is
	// never stored — the row holds a hash, so a database backup yields no
	// usable credentials.
	CreateRefreshToken(ctx context.Context, in NewRefreshToken) (plaintext string, expiresAt time.Time, err error)

	// RotateRefreshToken exchanges plaintext for a fresh token in the same
	// session, spending the presented one.
	//
	// Within grace of having been spent, a token may be exchanged again. That
	// window is not a concession to sloppy clients: BuildMax's CLI and Desktop
	// share one credentials file across independent processes, and two of them
	// refreshing at the same moment is normal rather than suspicious. Both
	// receive a usable token; both stay in the same session.
	//
	// Past the grace window a spent token means ErrRefreshTokenReused, and the
	// whole session is revoked first — logging out the legitimate holder is the
	// correct response when a credential may be in two hands. That error comes
	// back with UserID and SessionID populated and Plaintext empty, so the
	// caller can record what was revoked.
	RotateRefreshToken(ctx context.Context, plaintext string, now time.Time, ttl, grace time.Duration) (RotatedRefreshToken, error)

	// RevokeRefreshTokenSession revokes the refresh tokens the token belongs to
	// and reports whose session it was, so the caller can revoke the session
	// record too. An unknown token is not an error: logging out something already
	// gone is a success.
	RevokeRefreshTokenSession(ctx context.Context, plaintext string, now time.Time) (userID, sessionID string, err error)

	// DeleteExpiredRefreshTokens removes rows that can no longer be exchanged.
	DeleteExpiredRefreshTokens(ctx context.Context, before time.Time) (int64, error)
}

type RotatedRefreshToken struct {
	UserID    string
	SessionID string
	Plaintext string
	ExpiresAt time.Time
}

type SeenClaims struct {
	Email string
	Name  string
}

type SystemGrant struct {
	ID     string `json:"id"`
	UserID string `json:"user_id"`
	Role   string `json:"role"`
	// GrantedBy is the user_id of the admin who made the grant, or
	// AuditActorOperator when it came from the operator command, which runs
	// with database credentials and no signed-in identity. It is deliberately
	// the same string the matching audit event carries in ActorID: one act
	// should not have two names across two tables.
	GrantedBy string    `json:"granted_by"`
	GrantedAt time.Time `json:"granted_at"`
	// RevokedAt is nil while the grant is active. Revoking sets it rather than
	// deleting the row: who held authority and when is the question an
	// investigation asks, and a deleted row cannot answer it.
	RevokedAt *time.Time `json:"revoked_at,omitempty"`
}

type SystemGrantStore interface {
	// ActiveSystemRoles returns the roles userID currently holds, empty for
	// almost every caller. It is on the path of every authenticated admin
	// request, so it must stay a single indexed read.
	ActiveSystemRoles(ctx context.Context, userID string) ([]string, error)
	// ListSystemGrants returns grants newest first. includeRevoked adds the
	// retired ones, which is how the trail of who held authority is read.
	ListSystemGrants(ctx context.Context, includeRevoked bool) ([]SystemGrant, error)
	// GrantSystemRole grants role to userID. It returns ErrSystemGrantExists
	// when an active grant is already there, so a caller can report "already
	// an admin" rather than silently creating a second row.
	GrantSystemRole(ctx context.Context, userID, role, grantedBy string, now time.Time) (*SystemGrant, error)
	// RevokeSystemRole revokes userID's active grant for role and reports
	// whether one was found. Revoking an absent grant is not an error: the end
	// state is what was asked for.
	//
	// When keepLastHolder is true it refuses with ErrSystemGrantLastHolder
	// rather than remove the deployment's last effective holder, and it decides
	// and revokes in one atomic step so two concurrent revokes cannot both pass
	// the check and leave the role with nobody. When false — the operator shell,
	// which can undo a lockout — it revokes unconditionally.
	RevokeSystemRole(ctx context.Context, userID, role string, now time.Time, keepLastHolder bool) (bool, error)
	// CountActiveSystemGrants counts the effective holders of role: an active
	// grant on an account that is not disabled. A disabled account cannot
	// authorize a request, so it cannot be the holder that keeps the deployment
	// reachable — see docs/design/system-administration.md section 6.
	CountActiveSystemGrants(ctx context.Context, role string) (int, error)
}

type UnlinkIdentity struct {
	UserID     string
	IdentityID string
	// ActorID is the administrator performing the unlink, for the atomic audit
	// row. Empty records the action against the system actor.
	ActorID string
}

type User struct {
	ID                string     `json:"id"`
	Email             string     `json:"email"`
	Name              string     `json:"name"`
	QuotaTier         string     `json:"quota_tier,omitempty"`
	LastLoginAt       *time.Time `json:"last_login_at,omitempty"`
	LastLoginPlatform *string    `json:"last_login_platform,omitempty"`
	CreatedAt         time.Time  `json:"created_at"`
	// HasPassword reports whether this account can sign in with a password. The
	// hash itself never travels on this struct — see PasswordStore — so that no
	// handler can serialize it into a response by accident.
	HasPassword bool `json:"has_password"`
	// DisabledAt is nil for an ordinary account. Non-nil means every credential
	// this account holds is refused: password, login code, refresh token, the
	// access token it already has, and its webhook keys. Disabling is not
	// deletion — nothing is removed, and enabling reverses the state and
	// nothing else. See docs/design/system-administration.md section 8.
	DisabledAt *time.Time `json:"disabled_at,omitempty"`
}

type UserFilter struct {
	// Query matches the email as a substring.
	Query string
	// Disabled, when set, keeps only disabled (true) or only enabled (false)
	// accounts.
	Disabled *bool
	// HasPassword, when set, keeps only accounts that have set a password (true)
	// or have not (false) — the latter is who still needs a login code.
	HasPassword *bool
	// SystemRole, when non-empty, keeps only accounts holding that role as an
	// active grant.
	SystemRole string
	// Platform, when non-empty, keeps only accounts whose last login was on it.
	// An account that never logged in is excluded.
	Platform string
	// LastLoginAfter and LastLoginBefore, when set, bound the last-login time to
	// [after, before). An account that never logged in is excluded by either
	// bound, since it has no time to compare.
	LastLoginAfter  *time.Time
	LastLoginBefore *time.Time
}

type UserStore interface {
	// UserByEmail matches the address without regard to case, and returns
	// (nil, nil) when nobody has it. Login resolves the account this way and
	// compares nothing afterwards, so a case-sensitive implementation would
	// refuse people whose address is stored in another case.
	UserByEmail(ctx context.Context, email string) (*User, error)
	// GetUser returns the user by user_id, or (nil, nil) when not found.
	GetUser(ctx context.Context, userID string) (*User, error)
	// CreateUser creates a user with the given email. defaultQuotaTier is applied when non-empty. Returns ErrEmailExists if the email is already registered.
	CreateUser(ctx context.Context, email string, defaultQuotaTier string) (*User, error)
	// UpdateLoginMeta records the last login timestamp and platform for the user.
	UpdateLoginMeta(ctx context.Context, userID string, loginAt time.Time, platform string) error
	// ListUsers returns accounts newest first with the total count of accounts
	// the filter matched (not the page size), so a caller can page through them.
	ListUsers(ctx context.Context, filter UserFilter, limit, offset int) ([]User, int, error)
	// SetUserDisabled disables the account at the given time, or enables it
	// when disabledAt is nil. Returns ErrUserNotFound when there is no such
	// account.
	//
	// Disabling refuses with ErrSystemGrantLastHolder when the account is the
	// last effective holder of a system role: a disabled account cannot
	// authorize a request, so disabling the last one would leave the deployment
	// with nobody able to operate it. The check and the disable are one atomic
	// step so a concurrent grant revoke cannot slip between them.
	SetUserDisabled(ctx context.Context, userID string, disabledAt *time.Time) error
}

type UserWebhookKey struct {
	ID        string    `json:"id"`
	UserID    string    `json:"user_id"`
	KeyHash   string    `json:"-"` // SHA256 hex of plaintext key
	Name      string    `json:"name,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

type UserWebhookKeyStore interface {
	// CreateKey creates a new webhook key for the user. Returns plaintext key (e.g. whsec_...) and key_id. Caller must store plaintext securely; it is not persisted.
	CreateKey(ctx context.Context, userID, name string) (plaintextKey, keyID string, err error)
	// GetUserIDByKey looks up the user_id for the given plaintext key. Returns empty string if not found.
	GetUserIDByKey(ctx context.Context, plaintextKey string) (userID string, err error)
	// ListKeys returns key metadata for the user (no plaintext).
	ListKeys(ctx context.Context, userID string) ([]WebhookKeyMeta, error)
	// RevokeKey deletes the key by keyID if it belongs to the user.
	RevokeKey(ctx context.Context, userID, keyID string) error
}

type WebhookKeyMeta struct {
	KeyID     string    `json:"key_id"`
	Name      string    `json:"name,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}