authwire

type APIKeyView struct {
	ID    uuid.UUID `json:"id"`
	Name  string    `json:"name"`
	KeyID string    `json:"keyId"`
	// Kind is Integration or Personal. A client cannot tell them apart without
	// it, and they behave differently enough that an administration screen
	// showing a list of keys has to say which is which.
	Kind          string     `json:"kind"`
	Scopes        []string   `json:"scopes"`
	CIDRAllowList []string   `json:"cidrAllowList,omitempty"`
	CreatedAt     time.Time  `json:"createdAt"`
	ExpiresAt     *time.Time `json:"expiresAt,omitempty"`
	LastUsedAt    *time.Time `json:"lastUsedAt,omitempty"`
	RevokedAt     *time.Time `json:"revokedAt,omitempty"`
}

type AcceptAsMeRequest struct {
	InvitationID uuid.UUID `json:"invitationId"`
	Client       string    `json:"client"`
}

type AcceptRequest struct {
	Token  string `json:"token"`
	Client string `json:"client"`
}

type AccountView struct {
	// ID names the account — the person inside this tenant. It is not the
	// identity: somebody in two tenants has one identity and two accounts, and
	// this is the one that was just created.
	ID           uuid.UUID `json:"id"`
	TenantID     uuid.UUID `json:"tenantId"`
	EmailAddress string    `json:"emailAddress"`
	DisplayName  string    `json:"displayName"`
	// Kind and Role are the values the database stores, as strings, so that a
	// client sends back the same words it was given.
	Kind string `json:"kind"`
	Role string `json:"role"`
	// TimeZone is an IANA name, for example Europe/Stockholm. Empty means UTC.
	TimeZone  string    `json:"timeZone,omitempty"`
	CreatedAt time.Time `json:"createdAt"`
}

type AuthLogEntryView struct {
	ID uuid.UUID `json:"id"`
	// At is when it happened, in UTC.
	At time.Time `json:"at"`
	// Event is what happened — one of the values of the rig_auth_event enum.
	Event string `json:"event"`
	// Outcome is whether it worked: Succeeded or Failed, and no third value.
	Outcome string `json:"outcome"`

	// AccountID is who it happened to, absent when the attempt never resolved
	// to an account — which is what a wrong address looks like.
	AccountID *uuid.UUID `json:"accountId,omitempty"`
	// EmailAddress is the address as presented, lowercased. Present even when no
	// account matched, which is the case worth reading.
	EmailAddress string `json:"emailAddress,omitempty"`

	IPAddress string `json:"ipAddress,omitempty"`
	UserAgent string `json:"userAgent,omitempty"`

	// APIKeyID is the key involved, when one was.
	APIKeyID *uuid.UUID `json:"apiKeyId,omitempty"`
	// APIKeyRef is the public half of a key as presented, whether or not it
	// resolved to a row.
	APIKeyRef string `json:"apiKeyRef,omitempty"`

	// SessionID is the session family involved, named the way [TokenPair] names
	// it rather than after the root token it is stored as.
	SessionID *uuid.UUID `json:"sessionId,omitempty"`

	// Detail is whatever else was worth recording. Reuse detection puts the
	// original and current address and user agent here, which is what turns
	// "somebody replayed a token" into "somebody replayed it from Frankfurt".
	Detail map[string]any `json:"detail,omitempty"`
}

type CreateKeyRequest struct {
	Name          string     `json:"name"`
	Scopes        []string   `json:"scopes"`
	CIDRAllowList []string   `json:"cidrAllowList"`
	ExpiresAt     *time.Time `json:"expiresAt"`
	// Kind is Integration or Personal, and defaults to Integration.
	//
	// A personal key acts as its creator, so it cannot name a service account —
	// the manager refuses that combination and so does a CHECK on the table. An
	// integration key is the default because it is the one whose writes stay
	// attributable after the person who set it up has left.
	Kind string `json:"kind"`
	// ServiceAccountID is who the key acts as. It defaults to the caller, which
	// is the common case and the one that keeps the writes attributable.
	ServiceAccountID *uuid.UUID `json:"serviceAccountId"`
}

type CreateKeyResponse struct {
	Key APIKeyView `json:"key"`
	// Secret is shown exactly once. Nothing stored can produce it again, which
	// is what makes storing only a hash safe.
	Secret string `json:"secret"`
}

type CreateTenantRequest struct {
	Name string `json:"name"`
	// Client is web, mobile or machine, for the session the new tenant is
	// entered with.
	Client string `json:"client"`
}

type EmailCodeRequest struct {
	EmailAddress string `json:"emailAddress"`
}

type Handoff struct {
	TokenPair

	// IdentityToken and IdentityExpiresAt are as [SignInResponse] has them, and
	// they are the only members always present: somebody who belongs to no
	// tenant yet arrives with these and no pair.
	IdentityToken     string    `json:"identityToken"`
	IdentityExpiresAt time.Time `json:"identityExpiresAt"`
}

type ImpersonateRequest struct {
	AccountID uuid.UUID `json:"accountId"`
}

type InvitationPreview struct {
	// ID is what POST <base>/me/invitations/accept takes, for the case this
	// exists to serve second: somebody already signed in who has just followed
	// the link. It is safe to hand out because that endpoint refuses an
	// invitation that is not the caller's own.
	ID uuid.UUID `json:"id"`

	TenantID uuid.UUID `json:"tenantId"`
	// TenantName is the point of the whole endpoint. A page that cannot say
	// where somebody has been invited is a page that looks like phishing.
	TenantName string `json:"tenantName"`

	// EmailAddress is masked — "b***@school.example". Enough to recognise which
	// of your addresses this is, or to notice you are signed in as somebody
	// else, and not enough for a forwarded link to confirm an address to
	// whoever it was forwarded to.
	EmailAddress string `json:"emailAddress"`

	// Role is what accepting grants, so that accepting is an informed decision
	// rather than a button.
	Role string `json:"role"`
	// InvitedBy is the display name of whoever sent it, and empty when a key
	// sent it or when that person has since been removed — both of which a page
	// has to render rather than fail on.
	InvitedBy string `json:"invitedBy,omitempty"`

	ExpiresAt time.Time `json:"expiresAt"`
}

type InvitationToMeView struct {
	ID uuid.UUID `json:"id"`
	// TenantName is the part that means anything to somebody who has not been
	// there. The identifier is for the accept call.
	TenantID   uuid.UUID `json:"tenantId"`
	TenantName string    `json:"tenantName"`
	Role       string    `json:"role"`
	// InvitedBy is the display name of whoever sent it. It is here for the same
	// reason it is on the preview: a name is what makes "you have been invited"
	// something somebody recognises rather than something they distrust.
	InvitedBy string    `json:"invitedBy,omitempty"`
	CreatedAt time.Time `json:"createdAt"`
	ExpiresAt time.Time `json:"expiresAt"`
}

type InvitationView struct {
	ID           uuid.UUID `json:"id"`
	EmailAddress string    `json:"emailAddress"`
	DisplayName  string    `json:"displayName"`
	// Role is the role the invitation grants on acceptance, not one the invited
	// person holds yet.
	Role string `json:"role"`
	// InvitedBy is the display name of whoever sent it, and empty when a key
	// sent it or when that person has since been removed.
	InvitedBy string    `json:"invitedBy,omitempty"`
	CreatedAt time.Time `json:"createdAt"`
	// ExpiresAt is when the token stops working. A listed invitation past it is
	// history, not something still waiting to be accepted.
	ExpiresAt time.Time `json:"expiresAt"`
}

type InviteRequest struct {
	EmailAddress string `json:"emailAddress"`
	// DisplayName is what to call them in this tenant. Empty falls back at
	// accept time to the name the person already has.
	DisplayName string `json:"displayName"`
	// Role is optional and defaults to Basic.
	Role string `json:"role"`
}

type List[T any] struct {
	Data []T `json:"data"`
}

type Page[T any] struct {
	Data       []T        `json:"data"`
	Pagination Pagination `json:"pagination"`
}

type Pagination struct {
	// Offset is how many rows were skipped before this page.
	Offset int `json:"offset"`
	// Limit is the most rows this page could have held.
	Limit int `json:"limit"`
	// Total is every row matching the query, ignoring pagination. It is what
	// tells a caller whether there is another page.
	Total int64 `json:"total"`
}

type ProvisionRequest struct {
	EmailAddress string `json:"emailAddress"`
	DisplayName  string `json:"displayName"`

	// Kind and Role are optional: a person and Basic unless the caller says
	// otherwise. They are strings on the wire so that a client sends the same
	// words the database stores.
	Kind string `json:"kind"`
	Role string `json:"role"`

	TimeZone string `json:"timeZone"`
}

type RefreshRequest struct {
	RefreshToken string `json:"refreshToken"`
}

type SessionView struct {
	ID         uuid.UUID `json:"id"`
	CreatedAt  time.Time `json:"createdAt"`
	LastUsedAt time.Time `json:"lastUsedAt"`
	ExpiresAt  time.Time `json:"expiresAt"`
	IPAddress  string    `json:"ipAddress,omitempty"`
	UserAgent  string    `json:"userAgent,omitempty"`
	// AccountID is whose session it is. Always filled in, including in the
	// caller's own list where it is the caller: a member that is present for one
	// reading of an endpoint and absent for another is a member a client cannot
	// rely on.
	AccountID uuid.UUID `json:"accountId"`
	Client    string    `json:"client"`
	// Current marks the session making this request, so an interface can label
	// it rather than inviting somebody to revoke the tab they are looking at
	// without warning.
	Current bool `json:"current"`
}

type SignInResponse struct {
	TokenPair

	// IdentityToken proves who somebody is and names no tenant. It is what
	// the tenant picker runs on, and it is issued even alongside a session,
	// because switching tenant later is the same flow.
	IdentityToken     string    `json:"identityToken"`
	IdentityExpiresAt time.Time `json:"identityExpiresAt"`

	// Tenants is every one this person belongs to, so a client can draw the
	// picker without a second call. Empty means they belong to none yet, which is
	// an ordinary state and no longer a refusal.
	Tenants []TenantView `json:"tenants"`
}

type TenantView struct {
	TenantID   uuid.UUID `json:"tenantId"`
	TenantName string    `json:"tenantName"`
	TenantSlug string    `json:"tenantSlug"`
	AccountID  uuid.UUID `json:"accountId"`
	Role       string    `json:"role"`
	// Current marks the tenant this request was made in, so an interface can
	// show where somebody is without comparing identifiers itself.
	Current bool `json:"current"`
}

type TokenPair struct {
	AccessToken  string    `json:"accessToken,omitempty"`
	RefreshToken string    `json:"refreshToken,omitempty"`
	ExpiresAt    time.Time `json:"expiresAt,omitzero"`
	// RefreshExpiresAt is when the session itself ends. A client needs both:
	// one says when to refresh, the other says when to stop trying.
	RefreshExpiresAt time.Time `json:"refreshExpiresAt,omitzero"`
	SessionID        uuid.UUID `json:"sessionId,omitzero"`
}

type VerifyEmailCodeRequest struct {
	EmailAddress string `json:"emailAddress"`
	// Code is the digits as typed. Spaces and hyphens are tolerated; leading
	// zeros are part of the code and have to survive whatever a client does to
	// it, which is why it is a string and never a number.
	Code string `json:"code"`

	// Remember asks for a long session.
	Remember bool `json:"remember"`
	// Client is what will hold the session: "web", "mobile" or "machine".
	Client string `json:"client"`
}

type VerifyEmailRequest struct {
	Token string `json:"token"`
}