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

	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, so there is nothing to sign
	// in as.
	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 cannot sign in, which every sign-in path 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 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
	Log        authlog.Log
	Notifier   Notifier

	// EmailCode is the mailed-code sign-in. The zero value is off, and a
	// deployment with no provider configured either has no way in at all —
	// which [New] does not refuse, because a service that only provisions and
	// invites is a legitimate thing to build.
	EmailCode EmailCodeOptions

	// 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

	// AllowIdentity decides whether somebody nobody here has ever heard of may
	// become an identity. Nil admits everybody the doors above already let
	// through, which is what this package did before it existed.
	//
	// It is the same gate [github.com/simonjanss/rig/auth/oauth.Config] holds,
	// and one value is meant to be given to both: the question is about the
	// person rather than about how they are arriving, and a deployment with a
	// rule per door is a deployment that acquires an ungated one the next time a
	// door is added.
	//
	// See [github.com/simonjanss/rig/auth/identity.Gate] for the contract,
	// which is the part worth reading before writing one: it is asked about
	// strangers and nobody else.
	AllowIdentity identity.Gate

	// OnRegistered runs inside the transaction that creates a person rig has
	// never seen — asking for a sign-in code with a new address, where
	// [EmailCodeOptions.AllowProvisioning] allows it. Returning an error rolls
	// the whole thing back, so a retry is a clean retry rather than a conflict
	// with a half-made identity.
	//
	// It receives the service because the ordinary body is a call back into it —
	// [Service.Provision], bringing the newcomer into a starter tenant, or
	// [Service.Invite] to leave one waiting in their picker — 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.
	//
	// One thing to know before using it for anything expensive: it runs when the
	// code is *asked for*, not when it is typed back, because the row that holds
	// the code references the person. So a starter tenant made here may belong
	// to somebody who never finishes signing in.
	//
	// Nil, the default, creates the person and nothing else.
	OnRegistered func(ctx context.Context, accounts *Service, in Registered) error

	// OnJoined runs inside the transaction that accepts an invitation — after
	// the account exists, before the session is issued. Returning an error rolls
	// the whole acceptance back, so a retry is a clean retry rather than a
	// member with half a setup.
	//
	// It exists because of where an account now comes from. [Service.Provision]
	// is called by the application, so whatever else a new member needs — a
	// role's grants, a preferences row — is the caller's next line. Accepting an
	// invitation is called by rig's own handler, and this is that line.
	//
	// Reach the transaction with dbx.Tx(ctx). It does not receive the service:
	// the ordinary body is a write against the application's own tables rather
	// than a call back into this package.
	OnJoined func(ctx context.Context, in Joined) 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 sign-in endpoint, it is a guessing oracle with a queue.
	Limiter *throttle.Limiter
	Limits  throttle.Defaults

	MinDuration     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 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 EmailCodeOptions struct {
	// Enabled turns the flow on. [New] refuses it with no Notifier: a code
	// nobody receives is a door nobody can open.
	Enabled bool

	// Length is how many digits. Zero means [DefaultEmailCodeLength], and
	// anything between [MinEmailCodeLength] and [MaxEmailCodeLength] is
	// accepted.
	Length int
	// TTL is how long a code lasts. Zero means [DefaultEmailCodeTTL].
	TTL time.Duration
	// MaxAttempts is how many wrong guesses kill a code. Zero means
	// [DefaultEmailCodeMaxAttempts].
	//
	// It is a ceiling on one code rather than a rate limit on an address, and
	// the two are not substitutes: a limit counts failures over a rolling
	// window, so a fresh code arrives with the old code's failures still
	// counted and five fat-fingered attempts lock the address rather than
	// killing one code.
	MaxAttempts int

	// AllowProvisioning sends a code to an address rig has never seen, creating
	// the person when the code is asked for.
	//
	// Off by default, the way
	// [github.com/simonjanss/rig/auth/oauth.Config.AllowProvisioning] is and for
	// the same reason: it is the difference between a deployment anybody can get
	// an identity in and one where somebody has to be invited first. On, it is
	// self-registration — [Config.OnRegistered] runs in the transaction that
	// creates the person, which is the hook that puts a newcomer somewhere.
	//
	// The trade to know: with it on, a stranger typing an address creates a row
	// and runs that hook before proving anything. A starter tenant made this way
	// may belong to somebody who never types the code.
	AllowProvisioning bool
}

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
	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 is what the inviter called them, falling back to the name the
	// person already has when the inviter said nothing.
	DisplayName string
	// Role is what accepting will grant, which is worth showing: being invited
	// as an Admin is something to know before pressing the button.
	Role Role

	// InvitedByAccountID and InvitedByName are who sent it. The name is empty
	// when a key sent it, and when the person who did has since been removed —
	// both of which a landing page has to render rather than fail on.
	InvitedByAccountID *uuid.UUID
	InvitedByName      string

	CreatedAt time.Time
	ExpiresAt time.Time
}

type InviteInput struct {
	TenantID     uuid.UUID
	EmailAddress string

	// DisplayName is what to call them in this tenant. Empty falls back at
	// accept time to the name the person already has, rather than to a guess
	// made now: somebody who already signs in here has told you their name, and
	// an invitation should not overwrite it with the local part of an address.
	DisplayName string
	// Role defaults to Basic, and applies to this tenant only. Whether the
	// caller may hand out a higher one is the application's rule.
	Role Role

	// ByAccountID and ByAPIKeyID are who asked. They are not only audit columns
	// here: one of them becomes the created_by of the account accepting creates,
	// and the account's display name is what a landing page shows somebody who
	// has not signed in yet.
	ByAccountID *uuid.UUID
	ByAPIKeyID  *uuid.UUID
}

type Joined struct {
	TenantID   uuid.UUID
	AccountID  uuid.UUID
	IdentityID uuid.UUID
	Role       Role

	EmailAddress string
	DisplayName  string

	// InvitedBy is the account that sent the invitation, and nil when a key
	// sent it or when that person has since been removed.
	InvitedBy *uuid.UUID
}

type Kind 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 {

	// Now is the clock the expiry filters read, so that a test advancing its own
	// clock sees invitations expire the way Postgres would. Unset means
	// time.Now.
	//
	// The real store puts `expires_at > now()` in SQL; this double used to leave
	// it out entirely, which made it disagree with Postgres about a property
	// under test — the thing accountOrder below exists to avoid.
	Now func() time.Time

	// 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 {
	// SendEmailCode delivers a short numeric code somebody types back to sign
	// in. It is the one secret here that a person reads out rather than clicks,
	// so the mail wants it legible and on its own line.
	SendEmailCode(ctx context.Context, i *Identity, code string) error
	SendEmailVerification(ctx context.Context, i *Identity, token string) error
	SendInvitation(ctx context.Context, i *Identity, inv *Invitation, 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 PreviewInput struct {
	Token     string
	IPAddress string
	UserAgent string
}

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
}

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: the address's local part, which is all anybody
	// knows about somebody who has typed nothing but an address.
	DisplayName string

	IPAddress string
	UserAgent string
}

type RequestEmailCodeInput struct {
	// TenantID is only for the audit entry, and may be left empty: a code is
	// about an address rather than about a membership.
	TenantID     uuid.UUID
	EmailAddress 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 SignInIdentityInput struct {
	IdentityID uuid.UUID
	// TenantID says which tenant the session is for, and may be uuid.Nil, which
	// means "wherever they belong" — see [Service.SignInIdentity].
	TenantID uuid.UUID

	Remember  bool
	Client    session.Client
	IPAddress string
	UserAgent string
	// Method is how the person proved who they are — a provider name, "Google",
	// or "EmailCode" — and lands in the audit entry's detail. Empty means
	// nothing is claimed, which is what an invitation being accepted says.
	Method string
}

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 wherever they were
	// last — see [Service.SignInIdentity].
	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 "sign me out everywhere" mean what it says: a person is
	// global and their sessions are not, so ending every one of them has to reach
	// the tenants the request was not made from.
	AccountsForIdentity(ctx context.Context, identityID uuid.UUID) ([]*Account, error)

	// LastAccountForIdentity is the account a person most recently held a
	// session for, or nil when there is no record of one.
	//
	// It is what makes a sign-in that names no tenant land where somebody was
	// rather than where they started — see [Service.SignInIdentity]. The
	// account rather than the tenant, because an account is a person in a
	// tenant and the caller needs the row either way.
	//
	// It must skip an account or a tenant that is no longer active, for the
	// same reason [Store.AccountsForIdentity]'s caller does: landing somebody
	// somewhere [Store.TenantsForIdentity] will not list is worse than landing
	// them nowhere.
	LastAccountForIdentity(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.
	//
	// Ordered for a person to read rather than to match whichever account a
	// sign-in landed in: which one that was is *marked* — see
	// [SignInResult.TenantID] — so the two orderings have nothing to disagree
	// about.
	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 [Service.Provision] is the part that is the same everywhere — the
	// address is checked, the tenant's domains are honoured, and nothing is
	// written twice.
	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)

	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)
	// InvitationByID and InvitationByToken are one invitation, assembled the
	// way the two listings assemble theirs.
	//
	// They exist for the two callers that hold one invitation rather than a
	// person's set of them: the mail dispatcher, which has a delivery and needs
	// the tenant's name to put in the mail, and the preview, which has a token
	// out of a URL and needs to say what it is for. Neither filters on expiry —
	// that is a comparison against the service's clock, and putting it in SQL is
	// how the in-memory double and the real store end up disagreeing.
	InvitationByID(ctx context.Context, id uuid.UUID) (*Invitation, error)
	InvitationByToken(ctx context.Context, hash []byte) (*Invitation, error)

	// InvitationSlot is the invitation holding one person's place in one
	// tenant, or nil.
	//
	// What it reads is the unique index: one live invitation per person per
	// tenant, where live means not consumed and not revoked and says nothing
	// about expiry, because now() is not immutable and cannot be indexed on. So
	// this must not filter on expiry either — an expired invitation still holds
	// the slot, and [Service.Invite] is what clears it. A lookup that hid one
	// would leave the index to refuse the next invitation, and nothing in the
	// API could ever clear it.
	InvitationSlot(ctx context.Context, tenantID, identityID uuid.UUID) (*Invitation, error)

	// RevokeVerification cancels a row. 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)
	// VerificationByHash finds a row 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 row used. It must be a no-op on one that is
	// already consumed, so that two requests racing to redeem it cannot both
	// win.
	ConsumeVerification(ctx context.Context, id uuid.UUID, at time.Time) (bool, error)

	// LiveVerification is the newest row of a kind for one person that may still
	// be redeemed, or nil.
	//
	// It is how a sign-in code is found, and the reason there are two lookups
	// rather than one: a request carries the address and the code, not a token,
	// and six digits cannot be a key. [Store.VerificationByHash] is for the
	// kinds whose secret is long enough to be one.
	LiveVerification(ctx context.Context, identityID uuid.UUID, kind VerificationKind) (*Verification, error)

	// ChargeVerificationAttempt charges one wrong guess against a row and
	// revokes it when that was its last, reporting the count after the charge
	// and whether the row is now dead.
	//
	// It must be one statement. A read followed by a write is a window two
	// concurrent guesses both fit through, which is a handful of free attempts
	// against a secret that only has a million values.
	//
	// Revoked rather than a state of its own: [Verification.Usable] already
	// refuses a revoked row and so does the mail queue, so nothing else has to
	// learn that a ceiling exists. A row burned by guessing and one an
	// administrator withdrew are told apart by [Verification.Attempts].
	ChargeVerificationAttempt(ctx context.Context, id uuid.UUID, max int, at time.Time) (attempts int, dead bool, err 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 row
	// about the person rather than one tenant — confirming their address or
	// signing them in, 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 row 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

	// Attempts is how many wrong codes have been offered for this row, and it
	// matters for [KindEmailCode] alone. Six digits are guessable in a way a
	// 32-byte token is not, so a code has to die after a handful of tries rather
	// than merely be slowed down by a rate limit.
	Attempts int

	// What an invitation carries, and nil for every other kind. It is what
	// accepting creates the account from, which is what makes an invitation a
	// pending membership rather than a mail about a membership that already
	// exists.
	//
	// A database CHECK ties InvitedRole and InvitedToTenantID to the kind, so
	// an invitation with neither cannot be written at all.
	InvitedRole        *Role
	InvitedDisplayName string
	// InvitedByAccountID and InvitedByAPIKeyID are who asked. They become the
	// created_by pair of the account accepting creates, so the provenance
	// survives the invitation being consumed.
	InvitedByAccountID *uuid.UUID
	InvitedByAPIKeyID  *uuid.UUID
}

type VerificationKind string

type VerifyEmailCodeInput struct {
	// TenantID says which tenant the session is for, and may be left empty —
	// with the same meaning it has for a provider sign-in: nobody knows which
	// tenants an address belongs to before it has been proved, so a single
	// sign-in page asks for none and the picker sorts it out.
	TenantID     uuid.UUID
	EmailAddress string
	Code         string

	Remember  bool
	Client    session.Client
	IPAddress string
	UserAgent string
}