server

type AuditHeadShippingOptions struct {
	URL         string
	BearerToken string
	Interval    time.Duration
	HTTPClient  *http.Client
}

type BuildInfo struct {
	ServerVersion         string `json:"server_version"`
	ServerCommit          string `json:"server_commit"`
	ServerDate            string `json:"server_date"`
	DashboardRef          string `json:"dashboard_ref,omitempty"`
	DashboardBuilt        string `json:"dashboard_built,omitempty"`
	TaskExecutionDisabled bool   `json:"task_execution_disabled,omitempty"`
}

type KnownCapability struct {
	ID       string `json:"id"`
	Enforced bool   `json:"enforced"`
	Mutates  bool   `json:"mutates"`
	// Derived is whether this capability can answer for a node that has no
	// explicit enrolment. Enforcing one that cannot refuses the whole fleet on
	// the first request, so the console has to be able to say so.
	Derived bool `json:"derived"`
}

type Line struct {
	ID                 string `json:"id"`           // == LineHashID (stable handle)
	LineHashID         string `json:"line_hash_id"` // stable across re-probes; see lineHash / stableLineHandle
	LineID             string `json:"line_id,omitempty"`
	NodeID             string `json:"node_id"`
	NodeIdentityUUID   string `json:"node_identity_uuid,omitempty"`
	LineUUID           string `json:"line_uuid,omitempty"`            // design-15 D1: durable control-plane identity (vpnmeta/lineuuid)
	DownstreamLineUUID string `json:"downstream_line_uuid,omitempty"` // design-15 §6: declared chain edge target
	Core               string `json:"core"`                           // sing-box | xray | mihomo
	Source             string `json:"source"`                         // managed | discovered | imported
	Managed            bool   `json:"managed"`                        // under Lattice config management
	Name               string `json:"name"`
	Tag                string `json:"tag,omitempty"`
	// InboundTags is every sing-box inbound tag the node reported for the conf
	// file this line stands for. Tag above is that file's name, which equals the
	// inbound tag only by the helper script's convention; a hand-written file, or
	// one holding a relay pair, carries tags of its own. Traffic counters and
	// connection records arrive keyed by the core's real inbound tags, so these
	// are what those joins have to run against. Empty when the node's sing-box
	// helper predates the field, which leaves the convention in force and every
	// existing join unchanged.
	InboundTags []string `json:"inbound_tags,omitempty"`
	// NamedUsers and UnnamedUsers count the credentials on this line's conf file
	// that the node can and cannot count individually. sing-box builds its stats
	// user allowlist by name, so an unnamed credential never gets a per-user
	// counter and its traffic stays inside the inbound total. That is a
	// permanent property of the config rather than a failed attribution, and the
	// two are worth telling apart on screen. Both zero means the node did not
	// report, which is not the same as a line with no credentials.
	NamedUsers   int    `json:"named_users,omitempty"`
	UnnamedUsers int    `json:"unnamed_users,omitempty"`
	Type         string `json:"type,omitempty"` // protocol
	Transport    string `json:"transport,omitempty"`
	Security     string `json:"security,omitempty"`
	ListenHost   string `json:"listen_host,omitempty"`
	ListenPort   int    `json:"listen_port,omitempty"`
	PublicHost   string `json:"public_host,omitempty"`
	// PublicPort is where the outside actually reaches this line, when that
	// differs from ListenPort. Declared by the node, because a mapping that
	// lives in a provider's router cannot be read from the config here. Zero
	// means the listen port is also the public one.
	PublicPort int `json:"public_port,omitempty"`
	// ProviderEdge is the hostname a provider forwards into this node from. A
	// relay names it as its outbound server, so it is the only host under which
	// a chain into a NAT node can be matched back to the line that ends it.
	ProviderEdge   string   `json:"provider_edge,omitempty"`
	Domain         string   `json:"domain,omitempty"`
	OutboundRef    string   `json:"outbound_ref,omitempty"`    // direct | <host/tag> | "" unknown
	OutboundServer string   `json:"outbound_server,omitempty"` // downstream server host the outbound routes to
	OutboundPort   int      `json:"outbound_port,omitempty"`   // downstream server port the outbound routes to
	JumpEdges      []string `json:"jump_edges,omitempty"`      // line_hash_ids this line relays to
	// DeclaredJumpEdges is the subset of JumpEdges resolved from the sidecar's
	// declared downstream_line_uuid (design-15 §6), not inferred from outbound
	// host/port — the UI badges these as orchestrated edges.
	DeclaredJumpEdges []string `json:"declared_jump_edges,omitempty"`
	// design-17: a line backed by a server-owned managed-line definition (the
	// overlay) carries the definition's state. The join is by line_hash_id —
	// the compiler pre-computes the hash discovery will assign, so a
	// rediscovered applied line lands on its definition exactly.
	Overlay       bool   `json:"overlay,omitempty"`
	OverlayStatus string `json:"overlay_status,omitempty"` // planned | applied | failed
	OverlayUser   string `json:"overlay_user,omitempty"`
	UserCount     int    `json:"user_count"`
	UserKnown     bool   `json:"user_known"`       // false ⇒ discovered line, count not yet inspected
	Status        string `json:"status,omitempty"` // ok | pending | error | stale
	LastError     string `json:"last_error,omitempty"`
	// design-19: what the service is doing, as opposed to what the config
	// says. Status above answers "does the configuration check out";
	// ServiceState answers "is anything actually running and holding this
	// line's port". They must never be merged back into one field: their
	// disagreement is exactly the incident signal.
	ServiceState     string    `json:"service_state,omitempty"` // running | down | restarting | unknown
	ServiceCheckedAt time.Time `json:"service_checked_at,omitempty"`
	// ServiceNote is the probe's own account of why the state is not
	// "running": the refused candidate and the rule it failed, or the command
	// that could not run. Empty when the service is proven running, so a
	// consumer that prints it prints only what needs a hand.
	ServiceNote string            `json:"service_note,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"` // sing-box `_lattice` block (future enrich)
}

type LineBinding struct {
	LineHashID   string `json:"line_hash_id"`
	Enabled      bool   `json:"enabled"`
	FlowOverride string `json:"flow_override,omitempty"`
}

type LineGroup struct {
	NodeID   string `json:"node_id"`
	NodeName string `json:"node_name,omitempty"`
	Lines    []Line `json:"lines"`
}

type NodeProfileRuntime struct {
	NodeID          string                 `json:"node_id"`
	NodeName        string                 `json:"node_name,omitempty"`
	Managed         bool                   `json:"managed"`          // a Lattice ProxyNodeProfile exists
	Origin          string                 `json:"origin,omitempty"` // managed | discovered, when a profile exists
	Core            string                 `json:"core,omitempty"`
	CoreVersion     string                 `json:"core_version,omitempty"`
	ConfigPath      string                 `json:"config_path,omitempty"`
	StatsAPI        string                 `json:"stats_api,omitempty"`
	Applied         bool                   `json:"applied"`
	LastApplyAt     string                 `json:"last_apply_at,omitempty"`
	LastError       string                 `json:"last_error,omitempty"`
	InboundCount    int                    `json:"inbound_count"`
	DiscoveredCount int                    `json:"discovered_count"`
	DiscoveryStatus string                 `json:"discovery_status,omitempty"`
	DiscoveryError  string                 `json:"discovery_error,omitempty"`
	DiscoveredAt    string                 `json:"discovered_at,omitempty"`
	Collector       *UsageCollectorRuntime `json:"collector,omitempty"`
	Capabilities    []string               `json:"capabilities"`
}

type Options struct {
	// SubscriptionDecoy shapes the response every non-servable public
	// subscription request receives. Its zero value is an empty-bodied 404, which
	// a reverse proxy can replace with its own error page so /sub/<anything> and
	// an unknown path are indistinguishable.
	SubscriptionDecoy subscriptionDecoyOptions
	Store             *store.Store
	WebFS             fs.FS
	// LogStore is the dedicated bounded log-line database (logs.db). Nil disables
	// the log-ingestion feature: its endpoints return 503 and agents are told to
	// tail nothing. Injected by main (opened beside the state file with the same
	// cipher), mirroring Store.
	LogStore *logstore.Store
	// TraceStore is the sing-box connection trace database (trace.db). Nil
	// disables tracing: its endpoints return 503 and agents are told to collect
	// nothing. Injected by main beside LogStore with the same cipher.
	TraceStore    *tracestore.Store
	AdminUsername string
	AdminPassword string
	Build         BuildInfo
	SecureCookies bool
	// TrustProxy enables reading the client address from proxy headers
	// (CF-Connecting-IP, then X-Forwarded-For). Only enable when the server
	// sits behind a trusted reverse proxy / Cloudflare; otherwise clients can
	// spoof the header and evade per-IP rate limiting.
	TrustProxy bool
	// RequireTOTP forces interactive user sessions to enable TOTP before they can
	// use non-setup APIs. Existing password/SSO login still issues a session so
	// the operator can enroll, but withAuth gates every other route until TOTP is
	// active. Bearer PATs are not interactive sessions and are unaffected.
	RequireTOTP bool
	// PluginDir is the root directory of installed plugin bundles. Empty disables
	// plugin loading entirely.
	PluginDir string
	// PluginBundleCacheDir is the private content-addressed extraction cache for
	// signed manifest v2 archives. V2 plugins fail closed when it is empty.
	PluginBundleCacheDir string
	// PluginTrust is the operator policy used to verify plugin signatures at load
	// time. The zero value is fail-closed: host-risk plugins require a trusted
	// publisher signature.
	PluginTrust plugin.TrustPolicy
	// PluginRuntimeDir, when set, enables the Tier-2 system runner: each system
	// plugin gets a confined 0700 working dir under this path and its verified
	// artifact is executed there (design-08). Empty keeps the noop runner (broker
	// armed, artifact NOT executed) — the deliberate default.
	PluginRuntimeDir string
	// PluginRuntimeEnv is the explicit environment-variable allowlist forwarded
	// to Tier-2 system plugins. Empty means plugins receive only the runner's
	// fixed safe PATH/HOME/TMPDIR.
	PluginRuntimeEnv []string
	// PluginRuntimePool controls persistent stdio-json-v2 worker capacity and
	// retirement. Nil uses the system runner's safe host defaults.
	PluginRuntimePool *plugin.SystemPoolConfig
	// PublicURL is the externally-reachable base URL of this server (scheme +
	// host, no trailing slash), used to build the OIDC redirect URL. Required
	// for SSO login; empty disables the OIDC start/callback flow. It is also the
	// canonical source for the WebAuthn relying-party ID and origin (RPID = host,
	// RPOrigin = scheme://host[:port]); passkeys fail closed when it is empty.
	PublicURL string
	// MetricsToken enables the /metrics endpoint when non-empty. The endpoint
	// accepts only Authorization: Bearer <token>; empty keeps it hidden so public
	// deployments do not expose fleet runtime counters by default.
	MetricsToken string
	// CoreDNSBinary optionally pins the CoreDNS executable that self-host DNS
	// apply scripts may install. Empty preserves the fail-closed precondition
	// that coredns already exists on the node.
	CoreDNSBinary selfdns.CoreDNSBinarySource
	// GeoResolver maps node public IPs to advisory coordinates for the Fleet Map.
	// Nil keeps automatic lookup disabled; manual NodeGeo remains available.
	GeoResolver geoip.Resolver
	// AgentReleaseRepo is the trusted GitHub repository used by the simplified
	// node-agent update UX. Empty uses LatticeNet/lattice-node-agent.
	AgentReleaseRepo string
	// AuditHeadShipping periodically POSTs the verified, locally anchored audit
	// WAL head to an operator-controlled HTTPS endpoint. Empty URL disables it.
	AuditHeadShipping AuditHeadShippingOptions
	// TaskExecutionDisabled is a server-side fleet kill switch. When true, new
	// tasks are not queued and agents receive no task leases. Already leased
	// task results are still accepted so in-flight work can report terminal state.
	TaskExecutionDisabled bool
	// ApprovalAutoRules is the operator's JSON-encoded auto-approve policy list
	// (LATTICE_APPROVAL_AUTO_RULES). Empty keeps approvals fully manual — the
	// default. Malformed input is logged and ignored, never fatal.
	ApprovalAutoRules string
	// RenewalReminderInterval controls the machine-renewal reminder scheduler.
	// Zero uses the production default. DisableRenewalScheduler is intended for
	// tests that need full control over reminder evaluation.
	RenewalReminderInterval time.Duration
	DisableRenewalScheduler bool
	Logger                  *log.Logger
}

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

type SubscriptionSummary struct {
	UserID          string `json:"user_id"`
	Email           string `json:"email,omitempty"`
	Enabled         bool   `json:"enabled"`
	Eligible        bool   `json:"eligible"` // enabled AND not expired
	HasSubToken     bool   `json:"has_sub_token"`
	BindingCount    int    `json:"binding_count"`
	CredentialCount int    `json:"credential_count"`
	ExpiresAt       string `json:"expires_at,omitempty"`
}

type UsageByNode struct {
	NodeID    string `json:"node_id"`
	NodeName  string `json:"node_name,omitempty"`
	UsedBytes int64  `json:"used_bytes"`
	UserCount int    `json:"user_count"`
	At        string `json:"at,omitempty"`
}

type UsageByUser struct {
	UserID     string `json:"user_id"`
	Email      string `json:"email,omitempty"`
	UsedBytes  int64  `json:"used_bytes"`
	QuotaBytes int64  `json:"quota_bytes,omitempty"`
	Status     string `json:"status,omitempty"`
	LastSeen   string `json:"last_seen,omitempty"`
}

type UsageCollector struct {
	NodeID    string `json:"node_id"`
	NodeName  string `json:"node_name,omitempty"`
	Source    string `json:"source,omitempty"`
	Status    string `json:"status,omitempty"`
	Error     string `json:"error,omitempty"`
	CheckedAt string `json:"checked_at,omitempty"`
}

type UsageCollectorRuntime struct {
	Source    string `json:"source,omitempty"`
	Status    string `json:"status,omitempty"`
	CheckedAt string `json:"checked_at,omitempty"`
	LastOKAt  string `json:"last_ok_at,omitempty"`
	LastError string `json:"last_error,omitempty"`
}

type UsageRow struct {
	NodeID     string `json:"node_id"`
	NodeName   string `json:"node_name,omitempty"`
	UserID     string `json:"user_id"`
	Email      string `json:"email,omitempty"`
	LineHashID string `json:"line_hash_id,omitempty"` // empty until S3b sb-stats collector
	Bytes      int64  `json:"bytes"`
}

type VpnCredential struct {
	Protocol string `json:"protocol"`           // vless|vmess|trojan|shadowsocks|hysteria2|tuic|anytls
	UUID     string `json:"uuid,omitempty"`     // vless/vmess/tuic
	Password string `json:"password,omitempty"` // trojan/shadowsocks/hysteria2/anytls
	Flow     string `json:"flow,omitempty"`     // vless xtls flow
	Method   string `json:"method,omitempty"`   // shadowsocks cipher
	Security string `json:"security,omitempty"` // vmess security
}

type VpnUser struct {
	ID          string          `json:"id"`
	Email       string          `json:"email"`
	Name        string          `json:"name,omitempty"`
	Enabled     bool            `json:"enabled"`
	Credentials []VpnCredential `json:"credentials"`
	Bindings    []LineBinding   `json:"bindings"`
	SubID       string          `json:"sub_id,omitempty"`
	QuotaBytes  int64           `json:"quota_bytes,omitempty"`
	// QuotaPeriod is none (lifetime, the default) or monthly; QuotaResetDay is
	// the day of month (1..28) a monthly period starts. Period usage is summed
	// from the user-day rows, never stored.
	QuotaPeriod            string    `json:"quota_period,omitempty"`
	QuotaResetDay          int       `json:"quota_reset_day,omitempty"`
	ExpiresAt              time.Time `json:"expires_at,omitempty"`
	Group                  string    `json:"group,omitempty"`
	Comment                string    `json:"comment,omitempty"`
	SubscriptionGeneration uint64    `json:"-"`

	// MigratedFromProxyUser records the legacy ProxyUser this identity was derived
	// from, so the migration is idempotent and the subscription substrate is traceable.
	MigratedFromProxyUser string `json:"migrated_from_proxy_user,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}