api

type AppAuth struct {
	Store *appauth.Store
	// NewSession creates a kind=app session for uid and returns its raw
	// token and expiry. (sessions.Store.Create with Kind "app".)
	NewSession func(ctx context.Context, uid uuid.UUID, r *http.Request, deviceLabel string) (string, time.Time, error)
	// CallbackURL is where finish sends the browser: the app's fixed
	// callback (a Universal Link on rivolt.dev, rivolt://auth for a
	// self-hosted server). Never taken from the request (DA, condition 1).
	CallbackURL string
	// SecureCookie marks the state cookie Secure (as the session cookie).
	SecureCookie bool
	// MinIOSBuild, when > 0, is the oldest app build this server accepts;
	// /api/app/config reports it so the app can ask for an update.
	MinIOSBuild int
}

type AppleRevocation struct {
	DB *sql.DB
	// Token reads the account's kept refresh token ("" when it has none): appleid.Store.RefreshToken.
	Token func(ctx context.Context, uid uuid.UUID) (string, error)
	// Revoke revokes a refresh token at Apple: oidc.Service.AppleRevoke. nil (no Apple provider) queues every
	// revoke, which then expires unless Apple is configured again within 30 days.
	Revoke func(ctx context.Context, refreshToken string) error
	Sealer crypto.Sealer
	Log    *slog.Logger
}

type ArchiveRestorer interface {
	Restore(ctx context.Context, uid, vid uuid.UUID, month time.Time, dryRun, wait bool) (archive.RestoreResult, error)
}

type Deps struct {
	// SampleRetentionMonths is RIVOLT_SAMPLE_RETENTION_MONTHS (0 keeps raw
	// samples forever). A restore skips samples older than the cutoff, which
	// the next retention sweep would delete anyway.
	SampleRetentionMonths int
	// ArchiveRows reads the telemetry archive (N19) so the backup download
	// carries full detail for months thinning has reduced; nil when the
	// archive is off, and the backup is the database alone.
	ArchiveRows samples.ArchiveRows
	// ArchiveRestorer puts one archived vehicle-month back in full detail
	// (POST /api/admin/archive/restore); nil when the archive is off.
	ArchiveRestorer ArchiveRestorer

	Rivian rivian.Client
	// Accounts hands out per-user *rivian.LiveClient instances. The
	// /api/settings/rivian sign-in surface resolves the request user
	// to its private client via Accounts.For(uid), so concurrent
	// Login/Restore from different sessions can no longer corrupt
	// each other's tokens. nil when the stub client is in use
	// (nothing to sign into).
	Accounts rivian.AccountRegistry
	// Monitors hands out per-user *rivian.StateMonitor instances
	// that own the websocket subscription + recorder for that user's
	// vehicles. nil in mock/stub modes (no recorder needed there).
	Monitors    *rivian.MonitorRegistry
	PushService *push.Service
	// Per-user data-plane factories. The router resolves req.user →
	// uid → factory.For(uid) once per request, so handlers always
	// see stores scoped to the caller. nil-safe: handlers gate on
	// the resolved *Store being non-nil before reading.
	Drives   *drives.Factory
	Charges  *charges.Factory
	Samples  *samples.Factory
	Settings *settings.Factory
	Push     *push.Factory
	Trips    *trips.Factory
	// PackHealth is the per-vehicle derived-pack-capacity store.
	// Not a factory because samples are scoped by vehicle_id, not
	// user_id; the handler authorizes via the vehicleScoped
	// ownership middleware before reading. Nil-safe: the endpoint
	// returns 503 when unset.
	PackHealth *packhealth.Store
	// SettingsMgr exposes install-wide AI provider config (keys,
	// default models). Install-wide because the deployer pays the
	// LLM bill for every user. May be nil; the admin track
	// repopulates it from app_settings and gates the handlers
	// behind requireAdmin.
	SettingsMgr *settings.Manager
	// Auth, when non-nil, gates /api/* behind a session cookie
	// or trusted-proxy header. Whether unauthenticated requests
	// are 401'd is governed by AuthEnforced below; with Auth
	// non-nil but AuthEnforced false, sessions still resolve into
	// request context but the API stays open (legacy single-tenant
	// UX so docker-compose upgrades don't lock anyone out).
	Auth *auth.Service
	// Sessions, when set, mounts the signed-in user's device list under
	// /api/auth/sessions (list, revoke one, sign out everywhere else).
	Sessions *SessionsAPI
	// AuthEnforced flips on the requireUser middleware for /api/*.
	// True when at least one real issuer is configured (OIDC,
	// trusted-proxy, or the debug bypass).
	AuthEnforced bool
	// TermsLookup replaces the database read of a user's accepted Terms in the server-side Terms gate (tests).
	TermsLookup func(ctx context.Context, uid uuid.UUID) (db.Terms, error)
	// ImpersonationDisabled mirrors $RIVOLT_IMPERSONATION_DISABLED.
	// true makes the impersonation middleware ignore
	// X-Rivolt-Impersonate outright (regardless of caller role) and
	// is surfaced via /api/config so the SPA hides the admin
	// "View as" control instead of offering a dead button.
	ImpersonationDisabled bool
	// AdminDisabled mirrors $RIVOLT_ADMIN_DISABLED: the public site
	// serves no admin surface. /admin* and /api/admin* answer 404 (even
	// for an admin session), /api/auth/me reports an admin as "user" so
	// the SPA hides the link, and impersonation is off. Off by default;
	// for the split to admin.rivolt.dev (scratchpad admin-split.md).
	AdminDisabled bool
	// AdminOnly is RIVOLT_ADMIN_ONLY: the admin deployment. Every request
	// must carry a valid Cloudflare Access JWT (Access; nil denies all),
	// and only the admin surface exists under /api.
	AdminOnly bool
	// AdminHealth feeds GET /api/admin/health-summary (nil: every section reads unavailable).
	AdminHealth *adminhealth.Service
	// PlanLegs caches live planner calls and caps them per user (nil: neither).
	PlanLegs *planleg.Cache
	Access   *cfaccess.Verifier
	// AdminDebugProbes mirrors $RIVOLT_ADMIN_DEBUG_PROBES: mounts the raw
	// Rivian probes under /api/admin (trips/plan/raw, trips/plan/diag,
	// gql/type, gql/enum, gql/raw), which send arbitrary queries to Rivian
	// as the admin. Off by default; an operator turns it on for a session.
	AdminDebugProbes bool
	// OIDC, when non-nil, mounts /api/auth/oidc/* — the third
	// auth issuer alongside static creds and trusted-proxy
	// header. nil disables the social-login button row in the
	// SPA but doesn't affect any other code path.
	OIDC *oidc.Service
	// AppleNotifications, when non-nil, is POST /api/auth/apple/notifications: Apple's
	// server-to-server notifications (consent revoked, Apple account deleted, relay email
	// off or on). Public (Apple calls it, no cookie), behind a body cap and a per-IP limit.
	AppleNotifications http.Handler
	// Passkeys, when non-nil, adds WebAuthn sign-in to Rivolt's email accounts: the management routes under /api/auth/passkeys
	// and, with Hydra and Kratos wired, the passkey sign-in on the Hydra login page. nil: no passkey route exists.
	Passkeys *passkeys.Service
	// PasskeyStore is the passkey tables on the system pool, present whenever there is a database, whether or not WebAuthn is
	// configured. "Secure my account" and support's reset delete credentials through it: a deployment with passkeys off (the admin
	// site, or prod before the enable) can still hold rows, and must not skip the deletion because the sign-in service is not built.
	PasskeyStore passkeys.Store
	// PasskeyAccount replaces the database read of the signed-in account's email and name for the passkey routes (tests).
	PasskeyAccount func(ctx context.Context, uid uuid.UUID) (mail, display string, err error)
	// PasskeyMailer replaces the mailer for the "a passkey was added" notice (tests).
	PasskeyMailer interface {
		Send(ctx context.Context, m email.Message) error
	}
	// IOSAppIDs ("TEAMID.bundle.id", RIVOLT_IOS_APP_IDS) publishes the
	// iPhone app's associated domain: the AASA file and /app/callback. Empty:
	// neither is served.
	IOSAppIDs []string
	// AppAuth, when non-nil (with OIDC), mounts the iPhone app's sign-in
	// under /api/auth/app. nil: /api/app/config reports app_login=false.
	AppAuth *AppAuth
	// Hydra, when non-nil along with Kratos, mounts the custom
	// login + consent handlers under /api/auth/hydra. This makes
	// Rivolt the bring-your-own-UI for an Ory Hydra OAuth2 / OIDC
	// provider — downstream apps (ArgoCD, Grafana, etc.) federate
	// against Hydra and Hydra calls back into us for the user-
	// facing login prompt.
	Hydra  *hydra.Client
	Kratos *kratos.Client
	// Redis, when set, makes the failed-login limiters count across replicas (RedisPrefix is
	// the install's key prefix). Nil leaves them per pod.
	Redis       *redis.Client
	RedisPrefix string
	// HydraRememberFor controls how long Hydra remembers the
	// user's login + consent before forcing a fresh prompt. Zero
	// defers to Hydra's login_session lifespan. Sourced from the
	// RIVOLT_OIDC_HYDRA_REMEMBER_FOR env var in main.go.
	HydraRememberFor time.Duration
	WebFS            fs.FS
	Version          string
	// Changelog serves the release notes (GET /api/changelog and
	// /changelog.atom); nil leaves both unmounted.
	Changelog *changelog.Source
	// DB is the shared Postgres pool. Used by request middleware
	// that needs to answer "does this session user own this
	// vehicle?" without round-tripping through a per-user store.
	// Safe to be nil in legacy code paths that predate the
	// ownership middleware; ownership enforcement is only wired
	// when DB is non-nil.
	// DB is what request handling reads and writes: with RIVOLT_REQUEST_DATABASE_URL set it is the request pool (row-level security
	// applies, app.user_id comes from the request's context), otherwise the same pool as SystemDB. A site that forgot to say
	// otherwise therefore fails closed (an empty answer), never open.
	DB *sql.DB
	// SystemDB is the owner-role pool for paths that legitimately span users or run before a user is known: login, session and
	// token lookups, signup, account deletion, admin, signed links, pre-auth GETs. Using it is a decision with a comment at the
	// site (DA's RLS ruling). nil means DB (tests, and every deployment without the request pool).
	SystemDB *sql.DB
	// RequestPoolOn is set by main when DB is a separate request pool (RIVOLT_REQUEST_DATABASE_URL). With it set, New refuses to build
	// unless every system-side store is set too: the fallbacks (sysDB, systemSettings, systemSecrets) would otherwise run the system
	// sites on the request pool, where, for example, account deletion's last-admin count sees only the caller.
	RequestPoolOn bool
	// LoginForgetter forgets Hydra's remembered login for a user at plain sign-out (an IdentityRevoker). nil: nothing to forget.
	LoginForgetter LoginForgetter
	// SessionRevoker revokes every session and app token of a user (sessions.Store.RevokeAll), for support's "secure this account".
	SessionRevoker interface {
		RevokeAll(ctx context.Context, userID uuid.UUID) (int64, error)
	}
	// RememberedRevoker forgets the identity provider's remembered logins for a user (an IdentityRevoker), for the same.
	RememberedRevoker RememberedRevoker
	// SystemSettings is the settings factory on the system pool, for the sweeps that run without a request (the statement and weekly
	// recap emails). nil means Settings (no request pool).
	SystemSettings *settings.Factory
	// AuditKey keys the salted hash of a user id in the "account deleted" log line (derived from the cookie secret; empty
	// means a random key for the process).
	AuditKey []byte
	// Logger is the structured logger used by middleware for
	// infrastructure-class warnings (DB errors on ownership check,
	// etc.). nil is fine; events are dropped.
	Logger *slog.Logger
	// Flags is the operational-flag store (kill switch, future
	// pause_digest / pause_push rows). When nil the /api/admin/*
	// routes return 503 but the server still boots — the flag
	// surface is non-critical to rendering the app.
	Flags *flags.Store
	// AIBudget enforces the per-user daily cap on LLM-backed
	// endpoints (trip advice, drive efficiency). nil disables the
	// gate — the cost backstop fails open so no-DB and test paths
	// keep working.
	AIBudget *aibudget.Store
	// Secrets is the envelope-encrypted per-user blob store
	// (see internal/crypto, internal/secrets). Holds the
	// sealed rivian.Session and, later, AI provider keys and
	// per-user VAPID private keys. nil is tolerated so tests
	// and the mock/stub client don't have to stand up a
	// sealer; the Rivian sign-in surface becomes read-only
	// when it's absent.
	Secrets *secrets.Store
	// SystemSecrets is the secret store on the system pool, for the admin route that refreshes another user's Rivian session.
	// nil means Secrets (no request pool).
	SystemSecrets *secrets.Store
	// Metrics is the Prometheus instrumentation surface. When non-nil
	// the router wires per-handler latency + count tracking and
	// mounts /metrics. nil disables both — useful for tests that
	// don't want the global default registry pollution.
	Metrics *metrics.Metrics
	// Users, when non-nil, provisions user identities in the
	// configured IdP on POST /api/admin/users and DELETE.
	// nil (or a disabled provider) skips IdP provisioning —
	// the rivolt DB row is still created, callers must create
	// the OIDC identity out-of-band. See internal/idp.
	Users idp.UserProvider
	// AppleRevocation revokes (or queues the revoke of) an account's
	// Sign in with Apple token before any account deletion. nil-safe.
	AppleRevocation *AppleRevocation
	// SignupRequests, when non-nil, enables the public-facing
	// "request beta access" form at POST /api/signup/request and
	// the admin review surface at /api/admin/signup-requests/*.
	// Approve mints a magic-link signup token on the request row
	// and (if Email is wired) emails the requester. POST /api/signup
	// redeems that token to create the user.
	SignupRequests *signuprequests.Store
	// Email, when non-nil, sends transactional mail (currently just
	// signup approvals) via the Resend HTTP API. nil disables the
	// approval-email send; the admin still gets the code in the
	// approval response so it can be forwarded manually.
	Email *email.Client
	// StatementSigner signs the one-click unsubscribe links of the
	// monthly statement email (nil disables the unsubscribe routes).
	StatementSigner *statement.Signer
	// WeeklySigner signs the weekly recap's unsubscribe links (a scope of its
	// own, so they never verify as statement links). nil disables the recap.
	WeeklySigner *statement.Signer
	// BaseURL is the install's public origin (e.g. https://rivolt.dev),
	// sourced from $RIVOLT_PUBLIC_BASE_URL, else $RIVOLT_BASE_URL (the
	// admin deployment sets the former: its own host is behind Cloudflare
	// Access, so links it emails must point at the public site). Used
	// for user-facing links in emails: the magic-link signup URL
	// (admin approval and auto-approve) and the monthly statement's
	// links. Safe to leave empty in tests — the signup link falls back
	// to a relative path so copy-paste-into-the-same-tab still works.
	BaseURL string
	// ValhallaProxy, when non-nil, mounts a same-origin reverse
	// proxy at /api/maps/valhalla/* that forwards to a self-hosted
	// Valhalla. /api/config advertises whether the proxy is
	// mounted so the SPA picks the right base URL at boot. nil
	// leaves the route unmounted; the SPA renders raw GPS chords
	// without snapping.
	ValhallaProxy http.Handler
	// Valhalla is the self-hosted router the server itself calls (the overnight search puts a sparse path on the road with it); nil: none.
	Valhalla *maps.Valhalla
	// TilesProxy, when non-nil, mounts a same-origin reverse
	// proxy at /api/maps/tiles/* that forwards to a self-hosted
	// PMTiles file server (nginx serving the .pmtiles bundle
	// with byte-range support). nil leaves the route unmounted;
	// the SPA falls back to CARTO's public dark raster basemap.
	TilesProxy http.Handler
	// ChargersArchive, when non-nil, exposes a server-side
	// chargers-along-corridor query at /api/maps/chargers-along.
	// Backed by an in-memory copy of chargers.pmtiles so the SPA
	// can replace its per-tile HTTP fan-out with one POST.
	ChargersArchive *chargers.Archive
	// Photon is the self-hosted geocoder client. Empty BaseURL on
	// the client disables; /api/geocode falls through to
	// Open-Meteo's city-level service.
	Photon *geocoding.PhotonClient
	// WeatherClient is the shared Open-Meteo HTTP client used by
	// trip-planner weather adjustment. Distinct from the per-callsite
	// weather.NewClient() instances used elsewhere because the
	// planner reuses this in tight loops with MemCache. nil disables
	// weather adjustment (the plan response just omits the field).
	WeatherClient *weather.Client
	// WeatherCache memoises FetchHour results across overlapping plan
	// requests. Keyed on coarsened (lat, lon, hour). nil disables
	// caching; FetchHourCached falls through to the client.
	WeatherCache *weather.MemCache
}

type ForgetObserver func(entry string, err error)

type IdentityRevoker struct {
	Hydra  *hydra.Client
	Kratos *kratos.Client
	// Username is the account's username (db.RawUsernameByID on the system pool).
	Username func(ctx context.Context, uid uuid.UUID) (string, error)
}

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

type LoginForgetter interface {
	ForgetLogin(ctx context.Context, uid uuid.UUID) error
}

type PurgeResult struct {
	Off       bool
	DryRun    bool
	Cancelled int
	Warned    int
	Deleted   int
	// UnwarnableDeleted counts accounts with no verified address deleted at day
	// 120 without a warning; UnwarnableDue is its dry-run count.
	UnwarnableDeleted int
	UnwarnableDue     int // dry run
	WarnDue           int // dry run
	DeleteDue         int // dry run
	WarnedWaiting     int // dry run
}

type RememberedRevoker interface {
	RevokeRemembered(ctx context.Context, uid uuid.UUID) error
}

type RequestStores struct {
	Resolver   *db.VehicleResolverFactory
	Drives     *drives.Factory
	Charges    *charges.Factory
	Samples    *samples.Factory
	Settings   *settings.Factory
	Push       *push.Factory
	Trips      *trips.Factory
	PackHealth *packhealth.Store
	AIBudget   *aibudget.Store
	// Secrets is nil when there is no sealer (the Rivian sign-in surface is then read-only).
	Secrets *secrets.Store
}

type SessionsAPI struct {
	Store SessionsStore
	// Current returns the id of the session making the request, when it has one
	// (a cookie or app session; not header/Kratos/bypass auth). nil or false:
	// "current" is not marked and sign-out-everywhere-else is refused, since it
	// could not tell which session to keep.
	Current func(r *http.Request) (uuid.UUID, bool)
	// Remembered, when set, also forgets the identity provider's remembered logins after a revoke, so a revoked browser cannot
	// sign straight back in with no password (see RememberedRevoker). nil: nothing is remembered outside Rivolt (no Hydra).
	Remembered RememberedRevoker
	// Observe counts each clearing and its failures (see ForgetObserver); nil is a no-op.
	Observe ForgetObserver
}

type SessionsStore interface {
	List(ctx context.Context, userID uuid.UUID) ([]sessions.Session, error)
	RevokeOwned(ctx context.Context, userID, id uuid.UUID) (bool, error)
	RevokeOthers(ctx context.Context, userID, keepID uuid.UUID) (int64, error)
}