auth

type Actor struct {
	// UserID is the user making the change.
	UserID *uuid.UUID
	// IP and UserAgent are the client they made it from, if known.
	IP        *netip.Addr
	UserAgent string
}

type Apple struct {
	// BundleIDs are the iOS apps' bundle IDs, such as "com.example.app".
	// Identity tokens issued to any other app are refused.
	BundleIDs []string
}

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

type Config struct {
	// DB is the project's Postgres pool. Run Migrate on it first.
	DB *pgxpool.Pool

	// TrustedProxies are the networks allowed to set X-Forwarded-For and
	// X-Forwarded-User-Agent, normally the Next.js server on Railway's
	// private network. Requests from anywhere else use the connection's
	// own address and User-Agent.
	TrustedProxies []netip.Prefix

	Hooks Hooks

	// Logger receives the module's logs. Default: slog.Default().
	Logger *slog.Logger

	// Now returns the current time. Default: time.Now. Set it in tests to
	// control session expiry.
	Now func() time.Time

	// Mailer sends the module's emails. Required. Use mail/resend in
	// production.
	Mailer mail.Mailer

	// AppURL is the web app's base URL, for links in emails, e.g.
	// "https://app.example.com". Required. It must use https, except on
	// localhost.
	AppURL string

	// AppName appears in email subjects and text, e.g. "Acme", and as the
	// issuer in authenticator apps. Required.
	AppName string

	// EncryptionKey encrypts 2FA secrets: 32 random bytes, base64-encoded,
	// from an environment variable such as AUTH_ENCRYPTION_KEY. Generate one
	// with `openssl rand -base64 32`. Required. Keep a backup: if it's lost,
	// every user has to set up 2FA again.
	EncryptionKey string

	// AllowUnverifiedLogin lets users log in before verifying their email,
	// and makes sign-up log them in immediately. Off by default: new users
	// must verify their email, with their password, before they can log
	// in. See docs/api.md.
	AllowUnverifiedLogin bool

	// Emails overrides the default email templates.
	Emails Emails

	// DisableBreachCheck turns off checking new passwords against Have I
	// Been Pwned. The check is on by default; it sends only the first 5
	// characters of the password's SHA-1 hash, and is skipped if the API
	// doesn't answer within 2 seconds.
	DisableBreachCheck bool

	// OrgRoles are the roles a user can have in an organization, checked
	// by RequireOrg. They must include "owner", which always has every
	// permission. Leave nil if the app has no organizations.
	OrgRoles rbac.Roles

	// DisableOrganizationCreation removes POST /v1/organizations, for apps
	// that create organizations themselves with CreateOrganization.
	DisableOrganizationCreation bool

	// AppRoles are roles that apply across the whole app, such as staff
	// roles, checked by Require. Users have no app role until SetAppRole
	// gives them one. Leave nil if the app doesn't need them.
	AppRoles rbac.Roles

	// TwoFactorRoles are the privileged roles (the auth standard §6): staff
	// roles such as "support" always, and "owner" and "admin" when
	// organizations are shared by teams. Apps where each user gets their
	// own workspace may leave owner and admin out. A user with one of them,
	// in any organization, must have 2FA, and their sessions last at most
	// 12 hours. Until they set 2FA up, they can only set it up, read
	// GET /v1/users/me, and log out. Each name must be defined in OrgRoles
	// or AppRoles.
	TwoFactorRoles []string

	// OAuth turns on signing in with Google and GitHub.
	OAuth OAuth

	// DisableCleanup stops the module deleting expired data every hour in
	// the background. Call Auth.Cleanup on your own schedule instead.
	DisableCleanup bool

	// DisableNewDeviceEmails stops emailing users when they log in from a
	// browser or app and network they haven't used in the last 90 days.
	DisableNewDeviceEmails bool
}

type EmailData struct {
	// AppName is Config.AppName.
	AppName string
	// AppURL is Config.AppURL, for links that don't need a token, such as
	// the page to request a password reset.
	AppURL string
	// Link is the email's action link, with its token.
	Link string
	// ExpiresIn is how long Link works.
	ExpiresIn time.Duration
	// OrgName is the organization's name, for invitations.
	OrgName string
	// RecoveryCodesLeft is how many unused recovery codes the user has,
	// for RecoveryCodeUsed.
	RecoveryCodesLeft int
	// Provider is the sign-in provider's name, such as "Google", for
	// OAuthLinked and OAuthUnlinked.
	Provider string
	// Device is the browser or app's user agent, as it sent it, for
	// NewDeviceLogin. It's empty if it sent none. It comes from the client,
	// so treat it as untrusted text.
	Device string
	// LoggedInAt is when the login happened, in UTC, for NewDeviceLogin.
	LoggedInAt time.Time
}

type Emails struct {
	// VerifyEmail asks a new user to confirm their address.
	VerifyEmail func(EmailData) (subject, text, html string)
	// SignUpAttempt tells the owner of an existing account that someone
	// tried to sign up with their address. Link is a password reset link.
	SignUpAttempt func(EmailData) (subject, text, html string)
	// PasswordReset sends a password reset link.
	PasswordReset func(EmailData) (subject, text, html string)
	// PasswordChanged tells a user their password was changed or reset.
	// Link is empty.
	PasswordChanged func(EmailData) (subject, text, html string)
	// EmailChange asks a user to confirm a new address. It's sent to the
	// new address.
	EmailChange func(EmailData) (subject, text, html string)
	// EmailChanged tells the old address that the account's email was
	// changed. Link is empty.
	EmailChanged func(EmailData) (subject, text, html string)
	// Invitation invites someone to join an organization. OrgName is set.
	Invitation func(EmailData) (subject, text, html string)
	// TwoFactorEnabled, TwoFactorDisabled, and RecoveryCodesRegenerated
	// tell a user about changes to their 2FA. Link is empty.
	TwoFactorEnabled         func(EmailData) (subject, text, html string)
	TwoFactorDisabled        func(EmailData) (subject, text, html string)
	RecoveryCodesRegenerated func(EmailData) (subject, text, html string)
	// RecoveryCodeUsed tells a user a recovery code was used to log in or
	// to reset their password.
	// RecoveryCodesLeft is set. Link is empty.
	RecoveryCodeUsed func(EmailData) (subject, text, html string)
	// TwoFactorGuessing warns a user that someone got past their password
	// (or into their email, for a password reset) but then entered too
	// many wrong 2FA codes. Link is empty.
	TwoFactorGuessing func(EmailData) (subject, text, html string)
	// OAuthLinked and OAuthUnlinked tell a user a sign-in provider was
	// added to or removed from their account. Provider is set.
	OAuthLinked   func(EmailData) (subject, text, html string)
	OAuthUnlinked func(EmailData) (subject, text, html string)
	// NewDeviceLogin tells a user their account was logged in to from a
	// browser or app and network it hasn't been used from in the last 90
	// days. Device and LoggedInAt are set. Link is empty.
	NewDeviceLogin func(EmailData) (subject, text, html string)
}

type Event struct {
	ID uuid.UUID
	// UserID is who it happened to. It's nil for a failed login with an
	// unknown email, and once the user is deleted.
	UserID *uuid.UUID
	// ActorID is who did it, when that's someone else.
	ActorID *uuid.UUID
	// Type is one of the Event constants.
	Type      string
	IP        *netip.Addr
	UserAgent string
	Metadata  map[string]string
	CreatedAt time.Time
}

type EventPage struct {
	Events []Event
	// NextCursor fetches the next page with Events; it's empty on the
	// last page.
	NextCursor string
}

type GitHub struct {
	ClientID string
	// ClientSecret comes from an environment variable, such as
	// GITHUB_CLIENT_SECRET.
	ClientSecret string
}

type Google struct {
	ClientID string
	// ClientSecret comes from an environment variable, such as
	// GOOGLE_CLIENT_SECRET.
	ClientSecret string
}

type Hooks struct {
	// OnUserCreated runs inside the sign-up transaction. Returning an error
	// cancels the sign-up, so a project's own rows (e.g. a profile) are
	// created together with the user or not at all.
	//
	// The hook must write through tx, not the project's own pool: writes
	// through the pool aren't part of the transaction and wouldn't be
	// undone. Keep it quick, since the transaction stays open while it
	// runs.
	//
	// To refuse a sign-up, for example because the address isn't on an
	// allowlist, return ErrSignUpNotAllowed (or an error wrapping it). Any
	// other error is treated as a failure: logged as an error and, with
	// AllowUnverifiedLogin or a provider, answered with a 500.
	//
	// In verify first mode (the default), an email and password sign-up
	// answers before creating the user, so the response takes the same
	// time whether or not the address has an account. The hook then runs
	// just after the response, with the request's context values but not
	// its cancellation, and a failure can't change the 202 already sent.
	OnUserCreated func(ctx context.Context, tx pgx.Tx, u User) error

	// OnEvent runs after each security event is recorded, for projects
	// that also want auth events in their own tools, such as alerting or
	// Sentry. It runs in the request, so keep it quick and hand slow work
	// off. See the Event constants.
	OnEvent func(ctx context.Context, e Event)
}

type OAuth struct {
	Google *Google
	GitHub *GitHub
	// Apple turns on native Sign in with Apple in the iOS app. Apple isn't
	// offered on the web or Android.
	Apple *Apple
}

type Org struct {
	ID   uuid.UUID
	Role string
}

type Organization struct {
	ID        uuid.UUID
	Name      string
	CreatedAt time.Time
	UpdatedAt time.Time
}

type Session struct {
	ID uuid.UUID
	// Client is "web" or "mobile".
	Client    string
	ExpiresAt time.Time
	CreatedAt time.Time
}

type User struct {
	ID            uuid.UUID
	Email         string
	EmailVerified bool
	CreatedAt     time.Time
}