account

type AcceptInput struct {
	// Token is the single-use secret from the invitation mail. It is how somebody
	// who is not signed in redeems one.
	Token string
	// InvitationID names the invitation instead, for [Service.AcceptAsMe], where
	// the caller is signed in as the person it was addressed to. Exactly one of
	// the two is used, decided by which method is called.
	InvitationID uuid.UUID

	// Password sets a first password, and is required only for somebody who has
	// none — an invitation to their first tenant. Somebody who already signs
	// in here is joining a second one, and their existing password is the one
	// that works; a field that quietly replaced it would let an invitation to any
	// tenant change the credential for all of them.
	Password string

	Client    session.Client
	IPAddress string
	UserAgent string
}

type Account struct {
	ID       uuid.UUID
	TenantID uuid.UUID

	// IdentityID is the person this account belongs to, and nil exactly when
	// this is a service account — which is nobody, has no credential, and cannot
	// sign in.
	IdentityID *uuid.UUID

	// EmailAddress is a copy of the identity's, kept here so that listing the
	// people in a tenant is one query. For a service account it is a label.
	EmailAddress string
	DisplayName  string

	// Kind is whether this is a person or a service account an integration acts
	// as. A service account has no credential and cannot sign in, which Login
	// enforces rather than leaving to whoever wrote the row.
	Kind Kind

	// Role is the coarse level in this tenant: Owner, Admin or Basic. Finer
	// grants come from roles and permissions, and both reach a caller through
	// their claims. It is per account rather than per identity, so somebody can
	// be an Owner in one tenant and Basic in another.
	Role Role

	// TimeZone is an IANA name, for example Europe/Stockholm. Empty means UTC.
	//
	// It lives on the account because it is a property of the person rather than
	// of a request: a report somebody schedules for 9am means 9am where they are,
	// and a browser's offset is not available when nobody is looking at one.
	TimeZone string

	// IsActive is whether the account may be used. It is narrower than the
	// identity's: this removes somebody from one tenant.
	IsActive bool

	// CreatedBy and CreatedByKey are who asked for this account, for the audit
	// columns. Both are optional: rig itself creates accounts during a seed with
	// nobody to name.
	CreatedBy    *uuid.UUID
	CreatedByKey *uuid.UUID
}

type ChangePasswordInput struct {
	TenantID  uuid.UUID
	AccountID uuid.UUID

	CurrentPassword string
	NewPassword     string

	Client    session.Client
	IPAddress string
	UserAgent string
}

type Config struct {
	Store    Store
	Sessions *session.Manager
	// Identities issues the tenant-less credential a tenant picker runs on.
	// Required: a sign-in always produces one, including for somebody who lands
	// straight in a tenant, because switching later is the same flow.
	Identities *session.IdentityManager
	Hasher     *password.Hasher
	Policy     password.Policy
	Log        authlog.Log
	Notifier   Notifier

	// Outbox turns mail queueing on, and its presence is the whole switch.
	//
	// Nil is the inline path this package shipped with, byte for byte: a link is
	// minted in the request that asked for it and handed straight to the
	// Notifier. That is the default, and it has to be — queueing by default would
	// mean every existing deployment upgrades, keeps passing its Notifier, does
	// not add the cron job, and silently stops sending mail. That is a worse
	// outage than the one the queue fixes.
	//
	// Set it and a link is written to rig_identity_verification_delivery instead,
	// in the transaction that asked for it, and sent by [Service.DispatchMail] —
	// which something has to run. See [Outbox].
	//
	// The trade to know about before turning it on: a reset mail now arrives up
	// to one dispatch interval late, where inline it was sent inside the request.
	// What is bought is that a provider having a bad hour no longer fails the
	// request, spends the caller's rate-limit budget, and kills a token that was
	// already minted.
	Outbox Outbox
	// Mail is what the queue runs on. Every field is optional, and it is read
	// only when Outbox is set.
	Mail MailOptions

	// Tenants is what an application decides about making tenants: who may, what
	// a name may be, and what else a new one needs. Every field is optional; the
	// zero value lets anybody signed in make one called anything.
	Tenants TenantOptions

	// OnRegistered runs inside the transaction that creates a self-registered
	// identity — after the person and their credential exist, before the
	// identity session is issued. Returning an error rolls the whole sign-up
	// back, so a retry is a clean retry rather than a conflict with a half-made
	// account.
	//
	// It receives the service because the ordinary body is a call back into it —
	// [Service.Provision] with Invite set, bringing the newcomer into a starter
	// tenant — and the closure is handed to [New] before the service exists.
	// Reach the transaction itself with dbx.Tx(ctx), the same way a generated
	// repository does.
	//
	// Nil, the default, registers the person and nothing else.
	OnRegistered func(ctx context.Context, accounts *Service, in Registered) error

	// Limiter and Limits are what stop somebody guessing. A service built
	// without a limiter refuses to exist: a login endpoint with no lockout is
	// not a login endpoint, it is a password oracle with a queue.
	Limiter *throttle.Limiter
	Limits  throttle.Defaults

	MinDuration     time.Duration
	ResetTTL        time.Duration
	VerificationTTL time.Duration
	// InvitationTTL bounds an invitation. It is the longest of the three by
	// default: somebody invited on a Friday should still be able to join on
	// Monday, and an expired invitation means asking a colleague to send another.
	InvitationTTL time.Duration

	// RequireVerifiedEmail refuses a sign-in until the address is confirmed.
	RequireVerifiedEmail bool

	Now   func() time.Time
	Sleep func(ctx context.Context, d time.Duration)
}

type CreateTenantInput struct {
	// IdentityID is the person who will own it, established by their identity
	// session.
	IdentityID uuid.UUID
	Name       string
	// AllowedEmailDomains restricts later provisioning into it.
	AllowedEmailDomains []string

	IPAddress string
	UserAgent string
}

type Creator struct {
	IdentityID uuid.UUID
	// EmailAddress is theirs, lowercased — which is what a domain rule wants.
	EmailAddress string
	DisplayName  string
}

type Credential struct {
	ID         uuid.UUID
	IdentityID uuid.UUID

	PasswordHash string
	Algorithm    string
	Params       password.Params

	CreatedAt time.Time
	UpdatedAt *time.Time
}

type DeleteAccountInput struct {
	TenantID  uuid.UUID
	AccountID uuid.UUID

	At time.Time
	// ByAccountID and ByAPIKeyID are who did it, for the audit columns — who,
	// and through what.
	ByAccountID *uuid.UUID
	ByAPIKeyID  *uuid.UUID
}

type Delivery struct {
	ID uuid.UUID
	// VerificationID is the link this is the delivery of. Its token is rotated
	// before every attempt, so exactly one is live at a time.
	VerificationID uuid.UUID
	// Kind is which [Notifier] method to call, copied from the verification so a
	// claim needs no join.
	Kind VerificationKind

	State     DeliveryState
	DeliverAt time.Time
	// Attempts is how many times this has been claimed, including this one.
	Attempts int
}

type DeliveryState string

type Identity struct {
	ID uuid.UUID

	// EmailAddress is stored as the person typed it and matched lowercased.
	// Showing somebody a differently-cased version of their own address is a
	// small rudeness with no upside. It is unique across every tenant.
	EmailAddress string
	// DisplayName is what to call the person before any tenant has an opinion.
	// An account may override it, and mail uses this one.
	DisplayName string

	// IsActive is whether the person may sign in anywhere at all. An account's
	// own IsActive is narrower: it removes somebody from one tenant.
	IsActive        bool
	EmailVerifiedAt *time.Time

	// CreatedBy and CreatedByKey are who asked for this identity, for the audit
	// columns. Both are optional: a seed creates identities with nobody to name.
	CreatedBy    *uuid.UUID
	CreatedByKey *uuid.UUID
}

type ImpersonateInput struct {
	TenantID uuid.UUID
	// AdministratorID is who is really doing this. It travels with the session
	// through every rotation and lands in every audit entry the session writes.
	AdministratorID uuid.UUID
	AccountID       uuid.UUID

	IPAddress string
	UserAgent string
}

type Invitation struct {
	ID         uuid.UUID
	IdentityID uuid.UUID
	AccountID  uuid.UUID
	TenantID   uuid.UUID
	// TenantName is which tenant it is into. An invitation listed to the
	// person receiving it is otherwise a row of identifiers: they have not been
	// there yet, so the name is the only part they recognise.
	TenantName string

	EmailAddress string
	DisplayName  string
	Role         Role

	CreatedAt time.Time
	ExpiresAt time.Time
}

type Kind string

type LoginInput struct {
	// TenantID says which tenant the session is for, and may be left empty.
	//
	// Set it when the application already knows — a subdomain, a header, a path
	// segment — and the sign-in is refused unless the person belongs to that
	// tenant. Leave it empty and the person is signed in to one of their own
	// tenants, which is what a single sign-in page wants: nobody knows which
	// tenants an address belongs to until the password is checked, so asking
	// first is asking a question the visitor cannot answer.
	//
	// Either way the address is not looked up in a tenant: an address is one
	// person across every tenant, and the tenant only decides which of that
	// person's accounts the session belongs to.
	TenantID     uuid.UUID
	EmailAddress string
	Password     string

	Remember  bool
	Client    session.Client
	IPAddress string
	UserAgent string
}

type MailOptions struct {
	// ClaimTTL is how long this process's claim is honoured before another
	// dispatcher may take the row. Zero means [DefaultMailClaimTTL]; under
	// [MinMailClaimTTL] is refused.
	ClaimTTL time.Duration
	// SendTimeout bounds one call into a [Notifier]. Zero means
	// [DefaultMailSendTimeout]; ClaimTTL or longer is refused.
	//
	// It is the deadline on the context the notifier is handed, and it is
	// cooperative: a notifier that ignores it hangs its dispatcher anyway.
	SendTimeout time.Duration

	// MaxAttempts, BackoffBase and BackoffCap are the retry arithmetic. Zero
	// means the defaults, which span about eight hours.
	MaxAttempts int
	BackoffBase time.Duration
	BackoffCap  time.Duration

	// Jitter is where the spread on a retry comes from: given n it returns
	// something in [0, n). It exists to be replaced in a test and for nothing
	// else. Nil means math/rand/v2's.
	Jitter func(int64) int64
}

type MailReport struct {
	// Claimed is how many rows this pass took, and Sent how many a notifier
	// accepted.
	Claimed int
	Sent    int
	// Failed is how many reached MaxAttempts and stopped.
	Failed int
	// Rejected is how many a notifier refused permanently, with
	// [PermanentMailError], and which stopped on this attempt with the rest of
	// their schedule unspent.
	Rejected int
	// Retrying is how many failed this time and will be tried again.
	Retrying int
	// Deferred is how many were rescheduled at a notifier's own request rather
	// than on the computed backoff.
	Deferred int
	// Skipped is how many had nothing left to send: a link consumed, withdrawn,
	// or belonging to somebody who has since been deactivated.
	//
	// A steady non-zero one is not a problem. It is invitations being accepted
	// or withdrawn faster than the dispatcher runs, which is the queue working.
	Skipped int
	// Released is how many claims a clean shutdown gave back rather than leaving
	// to expire, and Abandoned how many the pass could not reach inside its
	// lease.
	Released  int
	Abandoned int
}

type Membership struct {
	TenantID   uuid.UUID
	TenantName string
	TenantSlug string

	AccountID uuid.UUID
	Role      Role
	IsActive  bool
}

type MemoryOutbox struct {

	// FailedReason is what the notifier last said about each delivery, exposed
	// so a test can assert on the sentence rather than only on the state.
	FailedReason map[uuid.UUID]string
	// contains filtered or unexported fields
}

type MemoryStore struct {

	// Domains are the allowed email domains per tenant, for the tests that care
	// about provisioning. Absent means no restriction, which is what an ordinary
	// tenant has.
	Domains map[uuid.UUID][]string
	// TenantNames name the tenants a tenant list reports.
	TenantNames map[uuid.UUID]string
	// contains filtered or unexported fields
}

type NewTenant struct {
	TenantID   uuid.UUID
	TenantName string
	TenantSlug string
	// AccountID is the first account, which holds OwnerRole.
	AccountID  uuid.UUID
	IdentityID uuid.UUID
}

type NoNotifier struct{}

type Notifier interface {
	SendPasswordReset(ctx context.Context, i *Identity, token string) error
	SendEmailVerification(ctx context.Context, i *Identity, token string) error
	SendInvitation(ctx context.Context, i *Identity, a *Account, token string) error
}

type Outbox interface {
	// Enqueue writes one delivery.
	//
	// It has to join the caller's transaction when there is one. The verification
	// row and this row are written together, and a verification without its
	// delivery is an orphan link nobody will ever mail — invisible, except as an
	// invitation in a listing that was never sent.
	Enqueue(ctx context.Context, d *Delivery) error

	// Claim takes up to limit due rows and stamps this process's lease on them,
	// charging each an attempt.
	//
	// The lease is what makes a crashed dispatcher recoverable: a row is still
	// Pending with a stale claim, and the next pass past it takes it. It must
	// skip rows another claimant is taking rather than queueing behind them.
	Claim(ctx context.Context, by uuid.UUID, now time.Time, ttl time.Duration, limit int) ([]Delivery, error)

	// RotateToken writes a fresh hash and expiry onto the verification a delivery
	// owns, and reports whether it changed anything.
	//
	// False means the link was consumed or withdrawn between being queued and
	// being sent, and the delivery is Skipped rather than sent or failed. It must
	// not touch a row that is already settled — that check and this write are one
	// statement, or two requests racing can both believe they hold the live
	// token.
	RotateToken(ctx context.Context, verificationID uuid.UUID, hash []byte, expiresAt time.Time) (bool, error)

	// MarkSent records that a notifier accepted a delivery.
	MarkSent(ctx context.Context, id uuid.UUID, at time.Time) error
	// MarkFailed records that a delivery is done being tried, with what the
	// notifier said last.
	MarkFailed(ctx context.Context, id uuid.UUID, reason string, at time.Time) error
	// MarkSkipped records that there was nothing left to send.
	MarkSkipped(ctx context.Context, id uuid.UUID, reason string, at time.Time) error
	// Retry puts a delivery back with a later deliver_at, keeping what the
	// notifier said so a pattern is visible before the cap is reached.
	Retry(ctx context.Context, id uuid.UUID, at time.Time, reason string, now time.Time) error

	// Abandon gives back the claim and the attempt for a row a pass never
	// reached. It must only affect rows this process still holds.
	Abandon(ctx context.Context, ids []uuid.UUID, by uuid.UUID, now time.Time) error
	// ReleaseClaims gives back every lease this process holds, keeping the
	// attempts — a shutdown gives up sends it made, not sends it never made.
	ReleaseClaims(ctx context.Context, by uuid.UUID, now time.Time) (int, error)
}

type ProvisionInput struct {
	TenantID     uuid.UUID
	EmailAddress string
	DisplayName  string

	// Kind defaults to a person. Pass KindService for the account an
	// integration's key acts as — it gets no identity at all, so there is nothing
	// to sign in with and nothing to phish.
	Kind Kind
	// Role defaults to Basic, and applies to this tenant only. Whether the
	// caller may hand out a higher one is the application's rule: this package
	// will set what it is told.
	Role Role
	// TimeZone is an IANA name, optional.
	TimeZone string

	// ByAccountID and ByAPIKeyID are who asked, for the audit columns. The HTTP
	// layer fills them from the claims; a caller reaching this directly should
	// fill them too, or the row will say a change came from nobody.
	ByAccountID *uuid.UUID
	ByAPIKeyID  *uuid.UUID

	// Invite sends a verification link, so the person can set a password and
	// arrive. Without a Notifier it does nothing, which is why it is a request
	// rather than an assumption.
	Invite bool
}

type RegisterInput struct {
	EmailAddress string
	DisplayName  string
	Password     string

	IPAddress string
	UserAgent string
}

type Registered struct {
	IdentityID uuid.UUID
	// EmailAddress as typed, trimmed. Lowercase it yourself for comparisons —
	// the address is one person's name for themselves, and the cased form is
	// what they wrote.
	EmailAddress string
	// DisplayName as resolved: what was sent, or the address's local part when
	// nothing was.
	DisplayName string

	IPAddress string
	UserAgent string
}

type RevokeInput struct {
	// TenantID is the caller's, and it bounds what can be withdrawn: an
	// invitation belongs to one tenant, and naming one from another tenant has to
	// answer the same way as naming one that does not exist.
	TenantID     uuid.UUID
	InvitationID uuid.UUID

	// ByAccountID and ByAPIKeyID are who did it, for the audit columns.
	ByAccountID *uuid.UUID
	ByAPIKeyID  *uuid.UUID
}

type Role string

type Service struct {
	// contains filtered or unexported fields
}

type SignInResult struct {
	IdentityID uuid.UUID
	// TenantID is the tenant the session landed in, and Nil when there was
	// none to land in.
	TenantID uuid.UUID

	// Session is the tenant session, or nil when there is no tenant to be
	// in. When a tenant was named it is that one; otherwise the oldest.
	Session *session.Pair
	// Identity is always issued, including alongside a session: signing in and
	// then switching tenants is one flow, and the picker needs a credential
	// that outlives whichever tenant was landed on.
	Identity session.Issued
	// Tenants are every one this person belongs to, so a client can draw the
	// picker without a second call.
	Tenants []Membership
}

type Store interface {
	// FindIdentityByEmail returns the person with a lowercased address, or nil
	// when there is none. It looks across every tenant, because an address is one
	// person. A missing identity is not an error: it is the ordinary answer to
	// somebody mistyping their address.
	FindIdentityByEmail(ctx context.Context, lowercased string) (*Identity, error)
	// FindIdentityByID returns a person, or nil.
	FindIdentityByID(ctx context.Context, id uuid.UUID) (*Identity, error)
	// InsertIdentity writes a new person.
	InsertIdentity(ctx context.Context, i *Identity) error
	// MarkIdentityVerified records that an address was confirmed. The address
	// belongs to the person, so confirming it counts in every tenant at once.
	MarkIdentityVerified(ctx context.Context, identityID uuid.UUID, at time.Time) error

	// FindByID returns an account, or nil.
	FindByID(ctx context.Context, tenantID, id uuid.UUID) (*Account, error)
	// AccountForIdentity returns a person's account in one tenant, or nil when
	// they do not belong to it.
	AccountForIdentity(ctx context.Context, tenantID, identityID uuid.UUID) (*Account, error)
	// AccountsForIdentity returns every account a person has, in every tenant.
	//
	// It is what makes a password change mean what it says: the credential is
	// global, so ending "every session" has to reach the tenants the request was
	// not made from.
	AccountsForIdentity(ctx context.Context, identityID uuid.UUID) ([]*Account, error)

	// TenantsForIdentity is the same set with the tenant's name attached, for
	// showing somebody where they can go.
	TenantsForIdentity(ctx context.Context, identityID uuid.UUID) ([]Membership, error)

	// Insert writes a new account.
	//
	// It is separate from the rest because creating one is not a flow this
	// package owns end to end: who may join a tenant is a product decision,
	// and Provision is the part that is the same everywhere — the address is
	// checked, the tenant's domains are honoured, nothing is written twice, and
	// no credential comes into existence by accident.
	Insert(ctx context.Context, a *Account) error

	// InsertTenant writes a tenant row.
	InsertTenant(ctx context.Context, t *Tenant) error

	// TenantDomains are the email domains this tenant's accounts may use, or
	// empty for no restriction.
	TenantDomains(ctx context.Context, tenantID uuid.UUID) ([]string, error)

	// Credential returns a person's password, or nil when they have none —
	// which is the case for somebody who only ever signed in through a
	// provider.
	Credential(ctx context.Context, identityID uuid.UUID) (*Credential, error)
	// SaveCredential creates or replaces a person's password.
	SaveCredential(ctx context.Context, c *Credential) error

	CreateVerification(ctx context.Context, v *Verification) error
	// PendingInvitations are the live invitations into one tenant: minted, not
	// redeemed, not withdrawn, not expired. It is what an interface lists so
	// somebody can change their mind.
	PendingInvitations(ctx context.Context, tenantID uuid.UUID) ([]Invitation, error)
	// InvitationsForIdentity are the live invitations addressed to one person,
	// across every tenant. The other side of PendingInvitations: that one is an
	// administrator looking at their tenant, this is somebody looking at
	// where they have been asked to go — which is the only thing they can see
	// before they belong anywhere.
	InvitationsForIdentity(ctx context.Context, identityID uuid.UUID) ([]Invitation, error)
	// RevokeVerification cancels a link. It must be a no-op on one that is
	// already consumed or revoked, and report whether it changed anything, so
	// two requests racing cannot both claim to have withdrawn it.
	RevokeVerification(ctx context.Context, id uuid.UUID, at time.Time) (bool, error)
	// SoftDeleteAccount removes somebody from a tenant, recording who did it.
	SoftDeleteAccount(ctx context.Context, in DeleteAccountInput) error
	// VerificationByHash finds a link by the hash of its token, or nil.
	VerificationByHash(ctx context.Context, hash []byte) (*Verification, error)
	// VerificationByID finds one by identifier, or nil.
	//
	// The by-identifier lookup exists for accepting an invitation from the
	// picker, where the caller is already signed in as the person it was
	// addressed to. The token proves somebody reached the mailbox; a session
	// proves who they are, which is the stronger claim of the two — so the
	// identifier is enough, and it is the only thing a listing hands out.
	VerificationByID(ctx context.Context, id uuid.UUID) (*Verification, error)
	// ConsumeVerification marks a link used. It must be a no-op on a link that
	// is already consumed, so that two requests racing to redeem one cannot
	// both win.
	ConsumeVerification(ctx context.Context, id uuid.UUID, at time.Time) (bool, error)

	InTx(ctx context.Context, fn func(ctx context.Context) error) error
}

type SwitchInput struct {
	// TenantID and AccountID are where the caller is now, from their claims.
	TenantID  uuid.UUID
	AccountID uuid.UUID
	// ToTenantID is where they want to be.
	ToTenantID uuid.UUID

	Client    session.Client
	IPAddress string
	UserAgent string
}

type Tenant struct {
	ID   uuid.UUID
	Name string
	// Slug is the URL-safe name, unique across every tenant.
	Slug string
	// AllowedEmailDomains restricts who may be provisioned into it. Empty means
	// no restriction.
	AllowedEmailDomains []string
	IsActive            bool
}

type TenantDraft struct {
	// ID is already decided, so a hook can use it — in a slug, or in a row of its
	// own keyed on it.
	ID uuid.UUID
	// Name is as typed, trimmed. A hook may rewrite it.
	Name string
	// Slug is empty unless a hook fills it in; otherwise it is derived after
	// Validate returns.
	Slug string
	// AllowedEmailDomains restricts who may be provisioned into this tenant
	// later. Empty means no restriction.
	AllowedEmailDomains []string

	// By is who is creating it, for a rule that depends on them.
	By Creator
}

type TenantOptions struct {
	// Allow decides whether this person may create a tenant at all.
	//
	// Nil means anybody signed in may. It runs before anything is written and
	// before Validate, so a refusal costs one function call.
	//
	//	Allow: func(_ context.Context, by account.Creator) error {
	//		if !strings.HasSuffix(by.EmailAddress, "@rig.app") {
	//			return rigerr.Forbidden("only rig.app may create tenants")
	//		}
	//		return nil
	//	}
	Allow func(ctx context.Context, by Creator) error

	// Validate checks and may rewrite what is about to be created.
	//
	// It is handed a pointer, so a hook that wants to normalize rather than refuse
	// can: title-casing a name, trimming a suffix, filling in a slug. What it
	// leaves behind is what gets written.
	//
	//	Validate: func(_ context.Context, t *account.TenantDraft) error {
	//		if t.Name != strings.Title(t.Name) {
	//			return rigerr.Invalid("a tenant's name must be capitalised")
	//		}
	//		return nil
	//	}
	Validate func(ctx context.Context, t *TenantDraft) error

	// Slug derives the URL-safe name. Nil uses [DefaultSlug].
	Slug func(name string, id uuid.UUID) string

	// OnCreated runs inside the transaction that made the tenant, after the row
	// and the first account exist and before the commit.
	//
	// This is where an application's own tables get their rows: the roles a tenant
	// starts with, a default project, a settings record. Returning an error rolls
	// the whole thing back, which is the point of it being here rather than after —
	// a tenant whose roles failed to seed is a tenant whose Owner can do nothing.
	//
	// Reach the transaction with [github.com/simonjanss/rig/runtime/dbx.Tx],
	// which is the same way a generated repository reaches it:
	//
	//	OnCreated: func(ctx context.Context, made account.NewTenant) error {
	//		tx, ok := dbx.Tx(ctx)
	//		if !ok {
	//			return errors.New("expected a transaction")
	//		}
	//		return seedRoles(ctx, tx, made.TenantID, keys)
	//	}
	OnCreated func(ctx context.Context, made NewTenant) error

	// OwnerRole is the level the first account gets. Empty means [RoleOwner].
	OwnerRole Role
}

type Verification struct {
	ID         uuid.UUID
	IdentityID uuid.UUID

	// InvitedToTenantID is the tenant an invitation is into, and nil for a link
	// about the person rather than one tenant — confirming their address or
	// resetting their password, both of which are global.
	InvitedToTenantID *uuid.UUID

	Kind      VerificationKind
	TokenHash []byte

	CreatedAt  time.Time
	ExpiresAt  time.Time
	ConsumedAt *time.Time

	// RevokedAt is when the link was cancelled, which is not the same as used.
	// An invitation somebody withdrew and one somebody accepted are different
	// things to find in an audit trail, so the table keeps both — the same
	// distinction rig_account_token makes between a rotation and a revocation.
	RevokedAt *time.Time
}

type VerificationKind string