auth

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

type CacheOptions struct {
	// Enabled turns it on. The zero value reads a row per authenticated
	// request, which is what rig did before this existed and is still the
	// correct choice for a deployment that is not paying for it.
	Enabled bool

	// TTL is how long an answer may be reused when no invalidation arrives.
	//
	// It is the backstop and not the guarantee. The guarantee is the channel: a
	// revocation publishes on the transaction that performed it, so every
	// replica that is listening has forgotten by the time that transaction
	// commits. This is what remains for a replica that was not.
	//
	// Zero takes [DefaultCacheTTL].
	TTL time.Duration

	// Channel is the Postgres channel invalidations travel on. Zero takes
	// [cache.DefaultChannel].
	//
	// It has to be an identifier — it reaches Postgres both quoted in a LISTEN
	// and as a parameter to pg_notify — and [cache.NewBus] panics on one that is
	// not, at startup, rather than failing at the first notification.
	Channel string

	// MaxEntries bounds each cache. Zero takes [cache.DefaultMaxEntries].
	MaxEntries int

	// Logger receives one line when invalidations stop arriving and one when
	// they resume. Zero uses [slog.Default].
	//
	// Worth setting, and worth reading. It is the only way anybody learns that
	// this module has gone back to reading a row per request: the fallback is
	// correct and silent, so nothing else about the server will say so.
	Logger *slog.Logger
}

type Config struct {
	// Pool is the database holding the foundation tables.
	Pool *pgxpool.Pool

	// Tenant resolves which tenant a request belongs to. The default reads the
	// X-Tenant-Id header.
	//
	// Replace it with whatever your deployment actually uses — a subdomain, a
	// path segment, a claim in a proxy's header. It is consulted only where a
	// tenant cannot be known some other way: login, a password reset, the OAuth
	// start. Once there is a session the tenant comes from the token.
	Tenant func(*http.Request) (uuid.UUID, error)

	// BasePath prefixes the endpoints. Default [DefaultBasePath].
	//
	// The provider routes sit under it: BasePath + "/oauth/{provider}/start".
	BasePath string

	// OnError renders a failure. The default is this package's own; pass your
	// API's error mapper so that an authentication failure looks like every
	// other failure.
	OnError func(w http.ResponseWriter, r *http.Request, err error)

	// AccessTTL, RefreshTTL and RememberTTL are how long the two kinds of token
	// last, and how long "remember me" extends the refresh token to. Zero means
	// the session package's defaults: 10 minutes, 12 hours, 30 days.
	AccessTTL   time.Duration
	RefreshTTL  time.Duration
	RememberTTL time.Duration

	// RotationLeeway is how long a refresh token stays usable after it has been
	// exchanged. Zero is [session.DefaultRotationLeeway], thirty seconds.
	//
	// Without one, a dropped response is a logout: the client never received the
	// new pair, retries with the old one, and has its whole family revoked for a
	// network blip. See [session.Config.RotationLeeway].
	RotationLeeway time.Duration

	// Cache holds the reads this package makes on every request — verifying a
	// session, verifying an API key — and withdraws them when they stop being
	// true.
	//
	// The zero value caches nothing, which is a row read per authenticated
	// request and the behaviour rig had before this existed. Setting
	// [CacheOptions.Enabled] is not a time-to-live over authentication: it opens
	// a Postgres channel, and every revocation this package performs publishes
	// on the transaction that performed it, so a permission taken away stops
	// working at the moment the change commits rather than when a timer expires.
	//
	// It is [New]'s to own. The bus is built, registered and started here and
	// closed by [Auth.Close], so there is no cache to wire, no publish to
	// remember, and no write path that can be left out.
	Cache CacheOptions

	// Policy is the password policy. The zero value is a minimum length of 12
	// and no composition rules, which is current advice.
	Policy password.Policy

	// BreachChecker is consulted when somebody sets a password. Nil skips the
	// check. password.HIBP is a k-anonymity client for haveibeenpwned that fails
	// open, which is the right way round: a network problem should not stop
	// somebody changing their password.
	BreachChecker password.BreachChecker

	// Notifier sends the mail a flow needs — a reset link, a verification link,
	// an invitation.
	//
	// Nil means none is sent, and it means that silently: account.NoNotifier is
	// substituted and returns success from every method, so in production nobody
	// can reset a password and nothing anywhere says so. Set one. (The one
	// combination that is refused is Mail.Queue with no notifier, which would
	// write rows nothing could ever send.)
	Notifier account.Notifier

	// Mail is the queue for those links: off by default, and turning it on means
	// running a job.
	//
	// Off, a link is minted in the request that asked for it and handed straight
	// to the Notifier, so a provider having a bad minute fails that request,
	// spends the caller's rate-limit budget, and kills a token that was already
	// minted. On, the link is written to the database in the same transaction and
	// sent by [Auth.DispatchMail] — which nothing runs on its own. Turning it on
	// without a cron entry is turning mail off.
	//
	// The trade in the other direction is latency: a queued reset mail arrives up
	// to one dispatch interval late.
	Mail MailOptions

	// RequireVerifiedEmail refuses a login until the address is verified.
	RequireVerifiedEmail bool

	// Grants answers what an account may do. Nil means nobody holds anything,
	// which makes every endpoint carrying a permission answer 403.
	//
	// This is where an application's authorization model plugs in, and rig ships
	// none. It derives the permission *keys* from the schema — api.Permissions()
	// in the generated package is the whole catalogue — and generates the check
	// that reads them off the claims. Deciding who holds which is yours: a table
	// of roles, a switch on the account's level, a claim on a federated token, a
	// map in a constant. Every product answers it differently and a framework
	// that picked one would be wrong for most of them.
	//
	// examples/auth has a worked implementation over role tables of its own, if a
	// starting point is more useful than a blank page.
	Grants authhttp.Grants

	// OnSessionRefresh replaces a session's payload every time it is refreshed.
	//
	// The payload is the application's own context for one session — which device
	// it is, when step-up authentication was last satisfied, which mode somebody
	// picked. It is set at sign-in through session.IssueInput.Payload, carried
	// forward by every rotation, and reaches a handler as tenancy.Claims.Extra,
	// where [github.com/simonjanss/rig/runtime/tenancy.Extra] decodes it into a
	// type of your own.
	//
	// Nil, the default, carries the previous payload forward unchanged. Set this
	// only to recompute it — the hook is handed the token being exchanged, so the
	// current payload is prev.Payload.
	//
	// Not for permissions. It is written at sign-in and again only at refresh, so
	// anything here outlives its own revocation by up to the refresh lifetime.
	// Grants answers that question, per request.
	OnSessionRefresh func(ctx context.Context, prev *session.Token) (json.RawMessage, error)

	// IdentitySessionTTL is how long the tenant-less credential lasts. Zero is
	// [session.DefaultIdentityTTL], half an hour, which is what picking a
	// tenant takes.
	IdentitySessionTTL time.Duration

	// AllowTenantCreation mounts POST /auth/tenants, where somebody signed in
	// makes one and becomes its Owner.
	//
	// Off by default. rig owns the mechanism — the tenant row, the first account,
	// the slug, the transaction — because that is the same everywhere and getting
	// it half-right leaves a tenant nobody can reach. The policy is Tenants below:
	// who may, what a name is allowed to be, and what else a new one needs.
	AllowTenantCreation bool

	// Tenants is what this application decides about making them. Every field is
	// optional; the zero value lets anybody signed in make one called anything.
	Tenants account.TenantOptions

	// AllowRegistration mounts POST /auth/register, where a stranger creates an
	// account with no tenant and lands in the picker.
	//
	// Off by default. Whether anybody may sign themselves up is a product
	// decision — invite-only and open registration are both ordinary — and rig
	// declines to pick one. Off means the route does not exist, rather than
	// answering 403 to something that is there.
	AllowRegistration bool

	// OnRegistered runs inside the transaction that creates a self-registered
	// identity, and an error rolls the sign-up back. The ordinary body is
	// accounts.Provision with Invite set — an application that starts every
	// newcomer in a demo or sandbox tenant leaves an invitation waiting in the
	// picker they land in. Nil registers the person and nothing else.
	//
	// See [github.com/simonjanss/rig/auth/account.Config.OnRegistered].
	OnRegistered func(ctx context.Context, accounts *account.Service, in account.Registered) error

	// Limits override the rate limits. The zero value is the documented set: 5
	// failed logins per address per 15 minutes, 50 per address range, 5 password
	// resets an hour, and so on.
	Limits throttle.Defaults

	// LogRetention is how long an entry in rig_auth_log is kept, and it is only
	// read by [Auth.PruneLog]. Zero, the default, keeps everything and makes that
	// method a no-op.
	//
	// It cannot be shorter than the longest window in Limits, and [New] refuses a
	// configuration where it is rather than clamping it. Those limits are counted
	// from this table: pruning inside a window deletes the failures a lockout is
	// adding up to, so the limit stops limiting and nothing says so. Refusing at
	// startup is the last place that mistake can be caught cheaply.
	LogRetention time.Duration

	// TrustedProxies are the networks whose X-Forwarded-For may be believed.
	//
	// Empty means none, and that is deliberate: an address read from a header a
	// client controls is an address a client chooses, and a rate limit keyed on
	// one is a rate limit an attacker walks around.
	TrustedProxies []netip.Prefix

	// OAuth wires the provider endpoints. Leave Providers empty and none are
	// mounted.
	OAuth OAuth

	// Now is the clock, for tests.
	Now func() time.Time
}

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

type GrantsCacheConfig struct {
	// TTL is how long an answer may be reused with no invalidation arriving.
	// Zero takes [DefaultCacheTTL].
	//
	// The backstop and not the guarantee, exactly as [CacheOptions.TTL] is —
	// with one difference worth being honest about. rig publishes every
	// invalidation for the reads it caches itself, so that TTL covers only a
	// replica that was not listening. Here the invalidations are yours, so it
	// also covers every write path you did not publish from. It is the cost of
	// a mistake as much as the cost of an outage.
	TTL time.Duration

	// MaxEntries bounds the map. Zero takes [cache.DefaultMaxEntries].
	MaxEntries int

	// Now is the clock, for tests.
	Now func() time.Time
}

type MailOptions struct {
	// Queue writes links to rig_identity_verification_delivery and sends them
	// from [Auth.DispatchMail] instead of from the request.
	Queue bool

	// ClaimTTL is how long one dispatcher's claim is honoured, and SendTimeout
	// bounds one call into the Notifier. SendTimeout has to be the shorter of
	// the two, and rig refuses the pair rather than explaining it.
	ClaimTTL    time.Duration
	SendTimeout time.Duration

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

	// Retention is how long a sent, failed or skipped delivery is kept before
	// [Auth.PruneMail] removes it. Zero keeps them forever, which is what every
	// other table in rig currently does and is not a recommendation.
	//
	// The link rows themselves are never pruned by this: they are the record of
	// who was invited and when.
	Retention time.Duration
}

type OAuth struct {
	// Providers are the identity providers to offer, from the oauth package:
	// oauth.Google(id, secret), oauth.Microsoft(id, secret), and so on.
	Providers []oauth.Provider

	// BaseURL is this application's own address, because the callback URL it
	// registers with a provider has to be absolute.
	BaseURL string

	// Origin overrides BaseURL for one request, for an application served at
	// several origins — a tenant per subdomain, most often. See
	// [oauth.Config.Origin], including what a provider will and will not
	// register.
	Origin func(r *http.Request) string

	// SigningKey signs the state parameter. Required, and at least 32 bytes —
	// [oauth.New] refuses anything shorter.
	//
	// It has to be the same key in every replica: a callback may arrive at a
	// different one than the one that started the flow, and a key invented per
	// process is a sign-in that fails whenever a load balancer is doing its job.
	SigningKey []byte

	// StateTTL bounds how long a sign-in round trip may take. Zero is
	// [oauth.DefaultStateTTL], ten minutes: generous for a redirect, short
	// enough that a stolen state parameter is useless.
	StateTTL time.Duration

	// AllowProvisioning creates an account the first time somebody signs in
	// with a provider. Without it a provider sign-in only works for an address
	// that already has an account.
	AllowProvisioning bool

	// AllowedReturnTo are the paths a sign-in may return to. An open redirect
	// is the classic mistake here.
	AllowedReturnTo []string

	// Insecure allows the state cookie over plain HTTP, for local development
	// where a browser would refuse the __Host- prefixed one. Never anywhere real.
	Insecure bool

	// OnSignIn finishes a provider sign-in. Nil issues a session and answers
	// with the same body a login does, which is [authhttp.Handler.SignIn].
	//
	// A browser flow usually wants a cookie and a redirect instead, and that is
	// the sort of decision this package cannot make: it depends on whether the
	// client is a single-page application, a server-rendered one, or a mobile
	// app catching a deep link.
	OnSignIn func(w http.ResponseWriter, r *http.Request, in oauth.SignIn) error
}

type Parts struct {
	Accounts *account.Service
	Sessions *session.Manager
	// Identities issues and verifies the credential somebody holds between
	// signing in and choosing a tenant.
	Identities *session.IdentityManager
	APIKeys    *apikey.Manager
	Limiter    *throttle.Limiter
	Stores     *authpg.Stores

	// Cache is the invalidation channel rig's own caches run over, or nil when
	// the project configured none.
	//
	// Here for the one thing rig cannot do on an application's behalf. rig
	// caches what it owns end to end — it makes the read and it makes every
	// write that withdraws it — and the read it does not own is Grants, over
	// role tables belonging to the application. A project that wants that answer
	// cached serves a topic of its own on this bus and publishes on it wherever
	// its roles change; see runtime/cache. Nothing in rig will do it for you,
	// because nothing in rig can see those writes.
	Cache *cache.Bus
}