models

type APIKey struct {
	// ID is the key's surrogate identifier, and what anything owned by the key points at. It
	// is stable across a rename and carries nothing derived from the credential.
	ID string `json:"id"`
	// Digest is the SHA256 hash of the key's plaintext, and is what identifies the key
	// everywhere it is resolved. The plaintext is never persisted.
	Digest string `json:"-"`
	// Name is an external identifier for a given API key. It is not unique per document but
	// is unique per tenant ID.
	Name string `json:"name"`
	// TenantID is the API key's namespace ID.
	TenantID string `json:"tenant_id"`
	// Role defines the permissions of the API key. It must be equal to or less than the creator's role.
	Role authorizer.Role `json:"role" validate:"required,oneof=administrator operator observer"`
	// CreatedBy is the ID of the user who created the API key.
	CreatedBy string `json:"created_by"`
	// CreatedAt is the creation date of the API key.
	CreatedAt time.Time `json:"created_at"`
	// UpdatedAt is the last update date of the API key.
	UpdatedAt time.Time `json:"updated_at"`
	// ExpiresIn is the expiration date of the API key. An expired key cannot be used for
	// authentication. When equals or less than 0 it means that are no expiration date.
	ExpiresIn int64 `json:"expires_in"`
}

type APIKeyConflicts struct {
	Digest string
	Name   string
}

type AccessPolicy struct {
	ID       string          `json:"id"`
	TenantID string          `json:"-"`
	Name     string          `json:"name"`
	Subject  PolicySubject   `json:"subject"`
	Filter   PublicKeyFilter `json:"filter"`
	// Logins are the unix logins this policy covers: exact names, or ["*"] for
	// any login.
	Logins []string `json:"logins"`
	// SourceIP restricts the policy to connections from these CIDRs (a client IP
	// in any of them matches). Empty matches any IP. A single host is a /32 (or
	// /128 for IPv6).
	SourceIP []string `json:"source_ip"`
	// Action is whether this policy grants (allow) or blocks (deny) the covered
	// access. Defaults to allow.
	Action PolicyAction `json:"action"`
	// RequireReauth gates access granted by this policy on a fresh
	// re-authentication (an out-of-band confirmation), even when the connecting
	// key is already an identity. Off by default; the identity alone is the norm.
	RequireReauth bool `json:"require_reauth"`
	// ReauthPeriod is the freshness window for RequireReauth, in seconds: a
	// re-authentication is only demanded when the identity has not re-authed
	// within it. The freshness belongs to the identity, not to a connection, so
	// within the window every login with that key goes straight through. nil or 0
	// means "always", the only setting that is genuinely per login. Only
	// meaningful when RequireReauth is set.
	ReauthPeriod *int `json:"reauth_period"`
	// SubjectMatches reports whether anything Subject names could reach a device. A policy for
	// which nothing can is inert: an allow grants nothing and a deny blocks nothing. A subject
	// may name nobody at all, or name only principals Authorize refuses before it reads a
	// policy: a member whose role lacks authorizer.DeviceConnect, or an expired API key.
	// Computed when a policy is read, never stored, so it follows membership and expiry
	// without a write.
	SubjectMatches bool `json:"subject_matches"`

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

type ActiveSession struct {
	UID      UID       `json:"uid"`
	LastSeen time.Time `json:"last_seen"`
	TenantID string    `json:"tenant_id"`
}

type AuthClaims struct {
	Claims string `json:"claims"`
}

type Billing struct {
	// CustomerID is the ID of the customer on the payment gateway.
	CustomerID string `json:"customer_id"`
	// Subscription is the namespace's subscription, or nil when the namespace has a customer but
	// never completed checkout. A nil Subscription is not a failed subscription: the namespace
	// keeps the free tier, exactly as a namespace with no Billing at all does.
	Subscription *BillingSubscription `json:"subscription,omitempty"`
	// CreatedAt is the time at which this billing was created.
	// It follows the RFC 3339 format, and it is empty on records written before the store began
	// to maintain it.
	CreatedAt string `json:"created_at,omitempty"`
	// UpdatedAt is the time at which this billing was last updated.
	// It follows the RFC 3339 format, and it is empty on records written before the store began
	// to maintain it.
	UpdatedAt string `json:"updated_at,omitempty"`
}

type BillingBlockReason string

type BillingEvaluation struct {
	// CanAccept indicates if the namespace can accept a new device.
	CanAccept bool `json:"can_accept"`
	// CanConnect indicates if the namespace can create a new connection SSH.
	CanConnect bool `json:"can_connect"`
	// Blocked names what denies the operation, and is empty when nothing does. The two reasons
	// need different answers from the user, so a caller must report them as different errors.
	Blocked BillingBlockReason `json:"blocked,omitempty"`
}

type BillingStatus string

type BillingSubscription struct {
	// ID is the ID of the subscription on the payment gateway.
	ID string `json:"id"`
	// Status is the current status of the subscription.
	Status BillingStatus `json:"status"`
	// CurrentPeriodEnd is the end of the current period.
	CurrentPeriodEnd int64 `json:"current_period_end"`
}

type Decision struct {
	Allowed bool
	// RequireReauth is set when access is allowed by a policy that carries the
	// re-auth flag; the gateway must run a fresh re-authentication before
	// proceeding, subject to ReauthPeriod.
	RequireReauth bool
	// ReauthPeriod is the matched policy's freshness window in seconds (nil/0 =
	// always). The gateway skips the re-auth when the identity re-authed within
	// it. Only meaningful when RequireReauth is set.
	ReauthPeriod *int

	// Reason is the cause of the refusal, empty when Allowed.
	Reason DenialReason
	// PolicyName is the policy that produced the refusal. Set for
	// ReasonDeniedByPolicy and ReasonPolicyUnevaluable only.
	PolicyName string
	// Login is the login the request asked for. Set for ReasonNoGrant only.
	Login string
}

type DenialReason string

type Device struct {
	// UID is the unique identifier for a device.
	UID string `json:"uid"`

	CreatedAt time.Time  `json:"created_at"`
	RemovedAt *time.Time `json:"removed_at"`

	Name      string          `json:"name" validate:"required,device_name"`
	Identity  *DeviceIdentity `json:"identity"`
	Info      *DeviceInfo     `json:"info"`
	PublicKey string          `json:"public_key"`
	TenantID  string          `json:"tenant_id"`

	// LastSeen represents the timestamp of the most recent ping from the device to the server.
	LastSeen time.Time `json:"last_seen"`
	// DisconnectedAt stores the timestamp when the device disconnected from the server.
	// When nil, it indicates the device is potentially online.
	//
	// Due to potential network issues, this field might be nil even when the device
	// is actually offline. For reliable connection status, check both this and
	// [Device.LastSeen] fields.
	DisconnectedAt *time.Time `json:"-"`
	// Online indicates whether the device is currently connected. This field is not
	// persisted to the database but is computed based on both [Device.LastSeen] and
	// [Device.DisconnectedAt] fields to determine the current connection status.
	Online bool `json:"online"`

	Namespace       string          `json:"namespace"`
	Status          DeviceStatus    `json:"status" validate:"oneof=accepted rejected pending unused"`
	StatusUpdatedAt time.Time       `json:"status_updated_at"`
	RemoteAddr      string          `json:"remote_addr"`
	Position        *DevicePosition `json:"position"`
	Acceptable      bool            `json:"acceptable"`

	CustomFields map[string]string `json:"custom_fields,omitempty"`

	// Ephemeral reports whether the device was enrolled with an ephemeral provisioning key and should be
	// removed automatically once it stays offline past EphemeralTimeout.
	Ephemeral bool `json:"ephemeral"`
	// EphemeralTimeout is how many minutes the device may stay offline before removal, copied from
	// the provisioning key at enrollment. Only meaningful when Ephemeral is true.
	EphemeralTimeout int `json:"ephemeral_timeout,omitempty"`
	// ProvisioningKeyID is the digest of the provisioning key the device enrolled with (a real key or the
	// namespace's legacy key). It attributes the device to its enrollment source.
	ProvisioningKeyID string `json:"provisioning_key_id,omitempty"`
	// OwnerID is the member who paired the device. The device leaves the namespace when they lose
	// the ability to accept devices in it. Empty for a team device, which leaves with nobody.
	OwnerID string `json:"owner_id,omitempty"`
	// LastEnrollmentAttemptAt is when the enrollment policy was last (re-)evaluated for the device. It
	// throttles reconciliation of a still-pending enrollment on the agent's periodic AuthDevice. Nil
	// until the first re-evaluation.
	LastEnrollmentAttemptAt *time.Time `json:"last_enrollment_attempt_at,omitempty"`

	Taggable `json:",inline"`
}

type DeviceAuth struct {
	Hostname  string          `json:"hostname,omitempty" validate:"required_without=Identity,omitempty,hostname_rfc1123" hash:"-"`
	Identity  *DeviceIdentity `json:"identity,omitempty" validate:"required_without=Hostname,omitempty"`
	PublicKey string          `json:"public_key"`
	TenantID  string          `json:"tenant_id"`
	// ProvisioningKey is an optional provisioning key presented at install time to auto-accept the device. It is
	// excluded from the UID hash so it never changes a device's identity.
	ProvisioningKey string `json:"provisioning_key,omitempty" hash:"-"`
}

type DeviceAuthRequest struct {
	Info     *DeviceInfo `json:"info"`
	Sessions []string    `json:"sessions,omitempty"`
	*DeviceAuth
}

type DeviceAuthResponse struct {
	UID       string `json:"uid"`
	Token     string `json:"token"`
	Name      string `json:"name"`
	Namespace string `json:"namespace"`
	// TenantID is the namespace the device was enrolled into. An agent that authenticated with a
	// provisioning key alone learns its namespace here, having had no tenant to send. Additive and
	// optional: older agents that don't read it are unaffected.
	TenantID string `json:"tenant_id,omitempty"`
	// Status is the device's enrollment status after this auth (accepted/pending/rejected). It lets a
	// current agent react to its authorization state (e.g. stop opening the tunnel when not accepted)
	// instead of connecting blind. Additive and optional: older agents that don't read it are
	// unaffected.
	Status DeviceStatus `json:"status,omitempty"`
	// Config holds device-specific configuration settings.
	// This can include various parameters that the device needs to operate correctly.
	// The structure of this map can vary depending on the device type and its requirements.
	// Example configurations might include network settings, operational modes, or feature toggles.
	// It's designed to be flexible to accommodate different device needs.
	Config map[string]any `json:"config,omitempty"`
}

type DeviceAuthStatus struct {
	Status DeviceStatus `json:"status"`
}

type DeviceConflicts struct {
	Name string
}

type DeviceIdentity struct {
	MAC string `json:"mac"`
}

type DeviceInfo struct {
	ID         string `json:"id"`
	PrettyName string `json:"pretty_name"`
	Version    string `json:"version"`
	Arch       string `json:"arch"`
	Platform   string `json:"platform"`
}

type DeviceLoginCode struct {
	Code      string `json:"code"`
	ExpiresIn int    `json:"expires_in_seconds"`
}

type DeviceLoginCodePreview struct {
	Kind      string          `json:"kind"`
	UID       string          `json:"uid,omitempty"`
	Name      string          `json:"name"`
	Identity  *DeviceIdentity `json:"identity"`
	Info      *DeviceInfo     `json:"info"`
	Namespace string          `json:"namespace,omitempty"`
	TenantID  string          `json:"tenant_id,omitempty"`
	Status    DeviceStatus    `json:"status,omitempty"`
}

type DevicePairing struct {
	Code      string       `json:"code,omitempty"`
	ExpiresIn int          `json:"expires_in_seconds,omitempty"`
	Status    DeviceStatus `json:"status"`
	TenantID  string       `json:"tenant_id,omitempty"`
}

type DevicePairingAccepted struct {
	UID       string `json:"uid"`
	TenantID  string `json:"tenant_id"`
	Namespace string `json:"namespace"`
	OwnerID   string `json:"owner_id,omitempty"`
}

type DevicePairingRequest struct {
	Hostname  string          `json:"hostname,omitempty"`
	Identity  *DeviceIdentity `json:"identity,omitempty"`
	Info      *DeviceInfo     `json:"info"`
	PublicKey string          `json:"public_key"`
	Code      string          `json:"code,omitempty"`
}

type DevicePairingStatus struct {
	Status   DeviceStatus `json:"status"`
	TenantID string       `json:"tenant_id,omitempty"`
	UID      string       `json:"uid,omitempty"`
	Name     string       `json:"name,omitempty"`
}

type DevicePosition struct {
	Latitude  float64 `json:"latitude"`
	Longitude float64 `json:"longitude"`
}

type DeviceStatus string

type DeviceTag struct {
	Tag string `validate:"required,min=3,max=255,alphanum,ascii,excludes=/@&:"`
}

type Endpoints struct {
	API string `json:"api"`
	SSH string `json:"ssh"`
}

type Filter struct {
	// Type os the filter. Type can be "property" or "operator". When Type is "property", the Params field must is set
	// to PropertyParams structure and when set "operator", the Params field must be set to OperatorParams structure.
	Type string `json:"type,omitempty"`
	// Params is the filter params. Params can be either PropertyParams or OperatorParams.
	Params any `json:"params,omitempty"`
}

type FirewallConnection struct {
	// Namespace is the namespace name, not its tenant ID.
	Namespace string `json:"namespace"`
	// Hostname is the device name within the namespace.
	Hostname string `json:"hostname"`
	// Username is the user being requested on the device, not the ShellHub user.
	Username  string `json:"username"`
	IPAddress string `json:"ip_address"`
}

type ID struct {
	ID string
}

type Info struct {
	Version   string    `json:"version"`
	Endpoints Endpoints `json:"endpoints"`
}

type InstanceAPIKey struct {
	// ID is the unique identifier of the key. It is a SHA256 hash of the prefixed plaintext key.
	ID string `json:"-"`
	// Name is an external identifier for a given key. It is unique across the instance.
	Name string `json:"name"`
	// CreatedBy is the ID of the instance administrator who created the key.
	CreatedBy string `json:"created_by"`
	// CreatedAt is the creation date of the key.
	CreatedAt time.Time `json:"created_at"`
	// UpdatedAt is the last update date of the key.
	UpdatedAt time.Time `json:"updated_at"`
	// ExpiresAt is the expiration date of the key. Unlike [APIKey], it is always set: an instance
	// key cannot be created without one.
	ExpiresAt time.Time `json:"expires_at"`
}

type Member struct {
	ID      string          `json:"id,omitempty"`
	AddedAt time.Time       `json:"added_at"`
	Email   string          `json:"email" validate:"email"`
	Role    authorizer.Role `json:"role" validate:"required,oneof=administrator operator observer"`
	// AccountStatus is the member's underlying user account status (confirmed or
	// not-confirmed). A not-confirmed member still has to finish setting up their account. It
	// is the account status, not the membership-invitation status (accepted/pending), which is
	// a separate concept.
	AccountStatus UserStatus `json:"account_status,omitempty"`
	// AwaitingApproval mirrors the member's user account flag: true while a namespace admin
	// provisioned them but a system admin has not approved the account yet. The account cannot
	// sign in until an admin approves it.
	AwaitingApproval bool `json:"awaiting_approval,omitempty"`
}

type MemberDeparted struct {
	TenantID string
	MemberID string
	// RemovedDevices are the UIDs of the devices that left with the member.
	RemovedDevices []string
	// APIKeyDigests are the digests of the API keys the member had created in the namespace.
	APIKeyDigests []string
}

type MemberView struct {
	ID       string          `json:"id,omitempty"`
	Name     string          `json:"name,omitempty"`
	Username string          `json:"username,omitempty"`
	Email    string          `json:"email"`
	Role     authorizer.Role `json:"role"`
	// Status is MemberStatusActive or MemberStatusAwaitingApproval.
	Status  string    `json:"status"`
	AddedAt time.Time `json:"added_at"`
}

type MembershipInvitation struct {
	ID              string                     `json:"-"`
	TenantID        string                     `json:"-"`
	UserID          string                     `json:"-"`
	InvitedBy       string                     `json:"invited_by"`
	CreatedAt       time.Time                  `json:"created_at"`
	UpdatedAt       time.Time                  `json:"updated_at"`
	ExpiresAt       *time.Time                 `json:"expires_at"`
	Status          MembershipInvitationStatus `json:"status"`
	StatusUpdatedAt time.Time                  `json:"status_updated_at"`
	Role            authorizer.Role            `json:"role"`
	Invitations     int                        `json:"-"`
	// Sig is the one-time signature that ties the invitation link to this row. It
	// replaces the former Redis "invite={sig}" token; validity is the row's ExpiresAt.
	Sig string `json:"-"`

	// NamespaceName isn't saved on the database
	NamespaceName string `json:"-"`
	// UserEmail isn't saved on the database
	UserEmail string `json:"-"`
}

type MembershipInvitationNotification struct {
	// Signature is the invitation's one-time signature; the accept-invite link is keyed by it.
	Signature string `json:"signature"`
	// ExpiresAt is when the invitation stops resolving, shown to the recipient as the link expiry.
	ExpiresAt time.Time `json:"expires_at"`
	// RecipientEmail is the invited address, already lowercased.
	RecipientEmail string `json:"recipient_email"`
	// RecipientName is the invitee's display name, empty for a not-yet-registered invitee (exactly
	// as before).
	RecipientName string `json:"recipient_name"`
	// ForwardedProto and ForwardedHost come from the originating request's X-Forwarded-* headers and
	// build the accept-invite link in the email.
	ForwardedProto string `json:"forwarded_proto"`
	ForwardedHost  string `json:"forwarded_host"`
}

type MembershipInvitationStatus string

type Namespace struct {
	Name     string             `json:"name"  validate:"required,hostname_rfc1123,excludes=.,lowercase"`
	Owner    string             `json:"owner"`
	TenantID string             `json:"tenant_id"`
	Members  []Member           `json:"members"`
	Settings *NamespaceSettings `json:"settings"`
	Devices  int                `json:"-"`

	DevicesAcceptedCount int64 `json:"devices_accepted_count"`
	DevicesPendingCount  int64 `json:"devices_pending_count"`
	DevicesRejectedCount int64 `json:"devices_rejected_count"`
	DevicesRemovedCount  int64 `json:"devices_removed_count"`

	Sessions   int       `json:"-"`
	MaxDevices int       `json:"max_devices"`
	CreatedAt  time.Time `json:"created_at"`
	Billing    *Billing  `json:"billing"`
	Type       Type      `json:"type"`
}

type NamespaceConflicts struct {
	Name string
}

type NamespaceDeviceLimit struct {
	MaxDevices           int
	DevicesAcceptedCount int64
}

type NamespaceSettings struct {
	SessionRecord          bool   `json:"session_record"`
	ConnectionAnnouncement string `json:"connection_announcement"`
	// SSHAccessMode selects the SSH authorization model for the namespace. In
	// "identity" mode every SSH login is gated on an out-of-band browser approval
	// (no device credential required) and governed by Access Policies; the legacy
	// key ACL and firewall checks are bypassed. "legacy" keeps the key/firewall
	// behavior unchanged. New namespaces are born "identity"; namespaces that
	// predate identity-first default to "legacy".
	SSHAccessMode string `json:"ssh_access_mode"`
	// SSHLegacyAllowed marks a namespace that predates identity-first
	// (grandfathered): only these may switch the SSH access mode back to legacy.
	// Namespaces born identity have it false and can never leave identity mode.
	SSHLegacyAllowed bool `json:"ssh_legacy_allowed"`
}

type OperatorParams struct {
	Name string `json:"name"`
}

type PolicyAction string

type PolicySubject struct {
	Type  PolicySubjectType `json:"type"`
	Value string            `json:"value"`
}

type PolicySubjectType string

type Principal struct {
	Kind PrincipalKind `json:"kind"`
	ID   string        `json:"id"`
}

type PrincipalKind string

type PrivateKey struct {
	Data        []byte    `json:"data"`
	Fingerprint string    `json:"fingerprint"`
	CreatedAt   time.Time `json:"created_at"`
}

type PropertyParams struct {
	Name     string `json:"name"`
	Operator string `json:"operator"`
	Value    any    `json:"value"`
}

type ProvisioningKey struct {
	// ID is the unique identifier of the provisioning key: the SHA256 digest of the plaintext key. The
	// plaintext itself is never returned, but the digest is safe to expose (it can't be reversed) and
	// lets a device's provisioning_key_id be matched back to its key.
	ID string `json:"id"`
	// Name is an external identifier. It is unique per tenant ID, not globally.
	Name string `json:"name"`
	// TenantID is the provisioning key's namespace ID.
	TenantID string `json:"tenant_id"`
	// Mode is the enrollment policy applied to devices that enroll with the key.
	Mode ProvisioningKeyMode `json:"mode"`
	// WebhookURL is the integrator endpoint called at enrollment when Mode is webhook.
	WebhookURL string `json:"webhook_url"`
	// WebhookSecret signs the webhook request (HMAC-SHA256) so the integrator can trust it. It is
	// internal-only and never serialized to clients.
	WebhookSecret string `json:"-"`
	// AllowedIdentities is the set of device identities accepted when Mode is allowlist, matched
	// against the identity the agent claims (DeviceIdentity.MAC), which is the interface address
	// only when SHELLHUB_PREFERRED_IDENTITY did not replace it. Anything outside it is rejected.
	AllowedIdentities []string `json:"allowed_identities"`
	// WebhookTimeout is how long (seconds) the synchronous webhook call may take before failing closed
	// to pending. Zero means the default.
	WebhookTimeout int `json:"webhook_timeout"`
	// WebhookCallbackTTL is how long (seconds) the deferred-decision callback token stays valid. Zero
	// means the default.
	WebhookCallbackTTL int `json:"webhook_callback_ttl"`
	// Reusable reports whether the key may enroll more than one device.
	Reusable bool `json:"reusable"`
	// UsageLimit caps how many devices may enroll with the key. Zero means unlimited.
	UsageLimit int `json:"usage_limit"`
	// UsedTimes is how many devices have enrolled with the key.
	UsedTimes int `json:"used_times"`
	// PendingDevices counts the key's devices still awaiting a decision.
	PendingDevices int `json:"pending_devices"`
	// LastUsedAt is when a device last enrolled with the key.
	LastUsedAt *time.Time `json:"last_used_at"`
	// Ephemeral marks devices enrolled with the key for automatic removal once offline past
	// EphemeralTimeout.
	Ephemeral bool `json:"ephemeral"`
	// EphemeralTimeout is how many minutes an ephemeral device may stay offline before removal
	// (1-10). Only meaningful when Ephemeral is true.
	EphemeralTimeout int `json:"ephemeral_timeout"`
	// Tags are the names of the namespace tags applied to devices enrolled with the key.
	Tags []string `json:"tags"`
	// Revoked reports whether the key has been permanently revoked. Revocation is one-way: a revoked
	// key can never enroll again. For a reversible pause, use Disabled instead.
	Revoked bool `json:"revoked"`
	// Disabled reports whether the key is temporarily paused. Unlike Revoked, it is reversible: a
	// disabled key stops enrolling but can be re-enabled at any time.
	Disabled bool `json:"disabled"`
	// Type discriminates the key's origin: a user-created key, or one of the namespace's two
	// auto-managed system keys (legacy, pairing). System keys are always valid and are not presentable
	// by an agent; see IsSystem.
	Type ProvisioningKeyType `json:"type"`
	// KeyEncrypted holds the plaintext key encrypted at rest (AES-GCM), so an admin can reveal it
	// later. It is internal-only and never serialized to clients (reveal returns the decrypted value
	// through its own endpoint).
	KeyEncrypted string `json:"-"`
	// KeyHint is a short, non-secret prefix of the plaintext key, used to render a recognizable
	// masked fingerprint in the list without exposing the secret.
	KeyHint string `json:"key_hint"`
	// CreatedBy is the ID of the user who created the key.
	CreatedBy string `json:"created_by"`
	// CreatedAt is the creation date of the key.
	CreatedAt time.Time `json:"created_at"`
	// UpdatedAt is the last update date of the key.
	UpdatedAt time.Time `json:"updated_at"`
	// ExpiresAt is the absolute date the key expires. A nil value means the key never expires.
	ExpiresAt *time.Time `json:"expires_at"`
}

type ProvisioningKeyConflicts struct {
	ID   string
	Name string
}

type ProvisioningKeyEvent struct {
	// ID is the unique identifier of the event.
	ID string `json:"id"`
	// ProvisioningKeyID is the digest of the provisioning key the device enrolled with.
	ProvisioningKeyID string `json:"provisioning_key_id"`
	// TenantID is the enrolling device's namespace ID.
	TenantID string `json:"tenant_id"`
	// DeviceUID is the enrolled device's UID at enrollment time.
	DeviceUID string `json:"device_uid"`
	// Hostname is the enrolled device's hostname at enrollment time.
	Hostname string `json:"hostname"`
	// Identity is the identity the device claimed at enrollment time, which is what an
	// allowlist key is matched against. It may be empty.
	Identity string `json:"identity"`
	// Info is the enrolled device's system info at enrollment time. It may be nil.
	Info *DeviceInfo `json:"info"`
	// SourceIP is the device's remote address at enrollment time. It may be empty (a pairing accept
	// materializes the device without an IP).
	SourceIP string `json:"source_ip"`
	// PublicKey is the enrolled device's public key (PEM) at enrollment time. It identifies the exact
	// credential: re-keying yields a new key here (and a new device), so it tells re-keyed enrollments
	// apart. May be empty for events recorded before this was captured.
	PublicKey string `json:"public_key,omitempty"`
	// Fingerprint is the SHA256 fingerprint of PublicKey, computed at read time (not stored). Empty when
	// PublicKey is absent or unparseable.
	Fingerprint string `json:"fingerprint,omitempty"`
	// Ephemeral reports whether the key marked the device ephemeral. Ephemeral enrollments are kept in
	// the history (audit completeness) so the UI can mark or filter them rather than drop them.
	Ephemeral bool `json:"ephemeral"`
	// ReRegistration reports whether this was a re-registration of a previously removed device rather
	// than a first registration.
	ReRegistration bool `json:"re_registration"`
	// Timestamp is when the enrollment was recorded.
	Timestamp time.Time `json:"timestamp"`
	// DeviceStatus is the enrolled device's *current* status (accepted/pending/rejected), joined live
	// at list time so the history can offer an accept/reject action. It is empty when the device no
	// longer exists (hard-deleted). It is not stored on the event row.
	DeviceStatus DeviceStatus `json:"device_status"`
	// DecidedStatus and DecidedAt freeze the enrollment's outcome on the event: the terminal status
	// (accepted/rejected) and when it was set. They are stamped once, when the device is accepted or
	// rejected, so the audit survives the device being removed (the live status can't). Nil/empty while
	// the enrollment is still pending.
	DecidedStatus DeviceStatus `json:"decided_status,omitempty"`
	DecidedAt     *time.Time   `json:"decided_at,omitempty"`
	// IsCurrent reports whether this is the device's newest enrollment event. A device removed and
	// re-registered shares one device row across several events, so the live status/action belongs to
	// the newest one alone; older events are historical. Computed at read time; drives the accept/reject
	// action only (the decision itself is frozen per-event above).
	IsCurrent bool `json:"is_current"`
}

type ProvisioningKeyMode string

type ProvisioningKeyType string

type PublicKey struct {
	Data        []byte    `json:"data"`
	Fingerprint string    `json:"fingerprint"`
	CreatedAt   time.Time `json:"created_at"`
	TenantID    string    `json:"tenant_id"`
	PublicKeyFields
}

type PublicKeyAuthRequest struct {
	Fingerprint string `json:"fingerprint"`
	Data        string `json:"data"`
}

type PublicKeyAuthResponse struct {
	Signature string `json:"signature"`
}

type PublicKeyFields struct {
	Name     string          `json:"name"`
	Username string          `json:"username" validate:"regexp"`
	Filter   PublicKeyFilter `json:"filter" validate:"required"`
}

type PublicKeyFilter struct {
	Hostname string `json:"hostname,omitempty" validate:"required_without=Tags,excluded_with=Tags,regexp"`
	Taggable `json:",inline"`
}

type PublicKeyUpdate struct {
	PublicKeyFields
}

type RecordedSession struct {
	UID      UID       `json:"uid"`
	Message  string    `json:"message"`
	TenantID string    `json:"tenant_id"`
	Time     time.Time `json:"time"`
	Width    int       `json:"width"`
	Height   int       `json:"height"`
}

type SSHApproval struct {
	Code        string          `json:"code"`
	TenantID    string          `json:"tenant_id"`
	Kind        SSHApprovalKind `json:"kind"`
	SessionUID  string          `json:"session_uid"`
	SSHID       string          `json:"sshid"`
	DeviceUID   string          `json:"device_uid"`
	DeviceName  string          `json:"device_name"`
	Username    string          `json:"username"`
	IPAddress   string          `json:"ip_address"`
	Fingerprint string          `json:"fingerprint"`
	Data        []byte          `json:"data"`
	// ReauthPeriod is the policy's window in seconds, on a reauth approval. Nil or
	// zero means the policy asks every time.
	ReauthPeriod *int             `json:"reauth_period"`
	State        SSHApprovalState `json:"state"`
	// DecidedBy is the account that resolved the approval. On an identity
	// approval it is the account the key binds to, and the gateway adopts it as
	// the session's identity.
	DecidedBy string `json:"decided_by"`
	// ConfirmationCode is minted when the approval is confirmed and shown only in
	// the console, to the person who confirmed it. They type it at the terminal,
	// which is what proves they reached the console rather than merely following
	// a link. Empty until confirmed.
	ConfirmationCode string    `json:"confirmation_code"`
	RequestedAt      time.Time `json:"requested_at"`
	ExpiresAt        time.Time `json:"expires_at"`
}

type SSHApprovalConfirmation struct {
	ConfirmationCode string `json:"confirmation_code"`
}

type SSHApprovalCreated struct {
	Code      string `json:"code"`
	ExpiresIn int    `json:"expires_in_seconds"`
}

type SSHApprovalKind string

type SSHApprovalRequest struct {
	SSHID       string           `json:"sshid"`
	DeviceName  string           `json:"device_name"`
	Username    string           `json:"username"`
	IPAddress   string           `json:"ip_address"`
	RequestedAt time.Time        `json:"requested_at"`
	State       SSHApprovalState `json:"state"`
	// Code echoes the correlation code so the page can display it for the user to
	// visually match against their approval prompt (anti-phishing).
	Code string `json:"code"`
	// Fingerprint is the presented key's fingerprint, shown front-and-center when
	// the key is becoming an identity.
	Fingerprint string `json:"fingerprint"`
	// Kind is what confirming does, and it is what the console branches the whole
	// screen on.
	Kind SSHApprovalKind `json:"kind"`
	// ReauthPeriod lets the console say how long confirming lasts, which is not
	// this login: the window is per identity, so other logins with the same key
	// skip the browser step until it lapses.
	ReauthPeriod *int `json:"reauth_period,omitempty"`
	// ExpiresIn is how much of the approval window is left, in seconds.
	ExpiresIn int `json:"expires_in_seconds"`
	// Namespace names where the key lands. The login carries it in the SSHID, so
	// it is not the console's current namespace: a member can approve a key into
	// a namespace they are not currently browsing.
	Namespace string `json:"namespace"`
}

type SSHApprovalState string

type SSHApprovalStatus struct {
	State  SSHApprovalState `json:"state"`
	UserID string           `json:"user_id,omitempty"`
	// ConfirmationCode is what the person was shown in the console and has to
	// type at the terminal. Empty unless State is confirmed.
	ConfirmationCode string `json:"confirmation_code,omitempty"`
}

type SSHCommand struct {
	Command string `json:"command"`
}

type SSHExitStatus struct {
	Status uint32 `json:"status"`
}

type SSHIdentity struct {
	ID       string `json:"id"`
	TenantID string `json:"-"`
	// PrincipalID is the id of the bound principal. Which table it names depends on
	// PrincipalType: a person is a row in users, an automation a row in api_keys.
	PrincipalID string `json:"principal_id"`
	// PrincipalName, PrincipalEmail, and PrincipalType describe the bound
	// principal, resolved for the management screen. They are not stored on the
	// identity row. PrincipalEmail is empty for anything that is not a person.
	PrincipalName  string        `json:"principal_name"`
	PrincipalEmail string        `json:"principal_email"`
	PrincipalType  PrincipalKind `json:"principal_type"`
	// Fingerprint is the SSH public key fingerprint in "SHA256:…" form.
	Fingerprint string `json:"fingerprint"`
	// Data is the OpenSSH public key the fingerprint is derived from.
	Data []byte `json:"-"`
	// Name is a user label for the key, e.g. "laptop".
	Name string `json:"name"`
	// Source is how the identity came to exist. It is a label, not a boundary:
	// only the approval path is asserted by the server, so nothing may authorize
	// on it without moving that decision server-side first.
	Source    SSHIdentitySource `json:"source"`
	CreatedAt time.Time         `json:"created_at"`
	// LastUsedAt moves on every connect (identity resolution).
	LastUsedAt *time.Time `json:"last_used_at"`
	// LastReauthAt moves only on a successful re-authentication, so it can gate
	// an Access Policy's reauth_period freshness window. Distinct from LastUsedAt.
	LastReauthAt *time.Time `json:"last_reauth_at"`
	// ExpiresAt, SingleUse, and ConsumedAt are the key's lifecycle: it is dead
	// once expired or consumed. Any identity may carry a TTL; only an identity
	// an API key owns may be single-use, for a one-shot automated run.
	// ExpiresAt nil means it never expires.
	ExpiresAt *time.Time `json:"expires_at"`
	SingleUse bool       `json:"single_use"`
	// ConsumedAt is stamped when a single-use key is burned by its one session.
	ConsumedAt *time.Time `json:"consumed_at"`
}

type SSHIdentitySource string

type SSHPty struct {
	Term    string `json:"term"`
	Columns uint32 `json:"columns"`
	Rows    uint32 `json:"rows"`
	Width   uint32 `json:"width"`
	Height  uint32 `json:"height"`
	// Not persisted (json:"-"); kept only so gossh.Unmarshal can consume it.
	Modelist []byte `json:"-"`
}

type SSHPtyOutput struct {
	Output string `json:"output"`
}

type SSHSignal struct {
	Name    uint32 `json:"status"`
	Dumped  bool   `json:"dumped"`
	Message string `json:"message"`
	Lang    string `json:"lang"`
}

type SSHSubsystem struct {
	Subsystem string `json:"subsystem"`
}

type SSHWindowChange struct {
	Columns uint32 `json:"columns"`
	Rows    uint32 `json:"rows"`
	Width   uint32 `json:"width"`
	Height  uint32 `json:"height"`
}

type Session struct {
	UID       string  `json:"uid"`
	DeviceUID UID     `json:"device_uid,omitempty"`
	Device    *Device `json:"device"`
	TenantID  string  `json:"tenant_id"`
	Username  string  `json:"username"`
	// UserID is the ShellHub account that authorized this session via browser
	// approval. Empty for password/public-key logins and web-terminal sessions.
	// It is not serialized; readers get Principal.
	UserID string `json:"-"`
	// APIKeyID is the API key this session acts as, when an automation opened it. Like UserID, it
	// is written here and read through Principal.
	APIKeyID string `json:"-"`
	// Principal is who opened the session: the person or the API key that presented the
	// credential, projected from UserID and APIKeyID. It is absent, rather than empty, under the
	// legacy access model, where a session has no principal by design.
	Principal     *Principal      `json:"principal,omitempty"`
	IPAddress     string          `json:"ip_address"`
	StartedAt     time.Time       `json:"started_at"`
	LastSeen      time.Time       `json:"last_seen"`
	Active        bool            `json:"active"`
	Authenticated bool            `json:"authenticated"`
	Recorded      bool            `json:"recorded"`
	Web           bool            `json:"web"`
	Position      SessionPosition `json:"position"`
	Events        SessionEvents   `json:"events"`
}

type SessionEvent struct {
	// Session is the session UID where the event occurred. It is not serialized.
	Session string `json:"-"`
	// Type of the session. Normally, it is the SSH request name.
	Type SessionEventType `json:"type"`
	// Timestamp contains the time when the event was logged.
	Timestamp time.Time `json:"timestamp"`
	// Data is the event's payload. Its shape follows the request: an object for one that carries
	// fields, and an empty string for one the protocol defines as having no body, such as shell.
	// It is omitted when the event carried no payload at all.
	Data any `json:"data,omitempty"`
	// Seat is the seat where the event occurred.
	Seat int `json:"seat"`
}

type SessionEventType string

type SessionEvents struct {
	// Types field is a set of sessions type to simplify the indexing on the database.
	Types []string `json:"types"`
	// Seats contains a list of seats of events.
	Seats []int `json:"seats"`
	// First is the type of the event the session opened with, taken from the request types that
	// open a channel: pty-req, shell, exec and subsystem. It is empty when the session recorded
	// none of them.
	First SessionEventType `json:"first,omitempty"`
	// Items is the session's timeline, oldest first, carried by the by-uid request alone and
	// never by the list. It excludes terminal output and is capped, so it is not necessarily
	// every event the session recorded, and it is absent both when there is nothing to show and
	// when the read failed.
	Items []SessionEvent `json:"items,omitempty"`
}

type SessionPosition struct {
	Longitude float64 `json:"longitude"`
	Latitude  float64 `json:"latitude"`
}

type SessionSeat struct {
	// ID is the identifier of session's seat.
	ID int `json:"id"`
}

type SessionUpdate struct {
	Recorded      *bool `json:"recorded"`
	Authenticated *bool `json:"authenticated"`
}

type Stats struct {
	RegisteredDevices int `json:"registered_devices"`
	OnlineDevices     int `json:"online_devices"`
	ActiveSessions    int `json:"active_sessions"`
	PendingDevices    int `json:"pending_devices"`
	RejectedDevices   int `json:"rejected_devices"`
}

type Status struct {
	Authenticated bool `json:"authenticated"`
}

type System struct {
	Setup bool `json:"setup"`
	// InstanceTenantID binds the instance to its namespace in single-namespace (Community)
	// deployments. When set, the store refuses any further namespace creation. Enterprise/Cloud
	// leave it empty (the store wrapper strips it) to keep multi-tenant behavior.
	InstanceTenantID string `json:"instance_tenant_id"`
	// Authentication manages the settings for available authentication methods.
	Authentication *SystemAuthentication `json:"authentication"`
}

type SystemAuthentication struct {
	Local *SystemAuthenticationLocal `json:"local"`
}

type SystemAuthenticationLocal struct {
	// Enabled indicates whether manual authentication using a username and password is enabled or
	// not.
	Enabled bool `json:"enabled" bool:"enabled"`
}

type Tag struct {
	ID        string    `json:"-"`
	TenantID  string    `json:"tenant_id"`
	Name      string    `json:"name"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type TagConflicts struct {
	Name string
}

type Taggable struct {
	// TagIDs contains the IDs of associated tags. It is used only for database storage
	// and relationship management. The field is not exposed in JSON responses to keep
	// the API focused on meaningful tag data rather than internal identifiers.
	TagIDs []string `json:"-"`

	// Tags contains the complete Tag objects associated with this resource. This field
	// is populated from TagIDs when retrieving data from the database, but is not
	// stored directly. It is used only for JSON serialization to provide clients
	// with full tag information.
	Tags []Tag `json:"tags"`
}

type Tenant struct {
	ID string
}

type Type string

type UID string

type User struct {
	ID string `json:"id,omitempty"`
	// Origin specifies the the user's signup method.
	Origin UserOrigin `json:"-"`

	// ExternalID represents the user's identifier in an external system. It is always empty when [User.Origin]
	// is [UserOriginLocal].
	ExternalID string `json:"-"`

	Status UserStatus `json:"status"`
	// MaxNamespaces represents the count of namespaces that the user can owns.
	MaxNamespaces  int       `json:"max_namespaces"`
	CreatedAt      time.Time `json:"created_at"`
	LastLogin      time.Time `json:"last_login"`
	EmailMarketing bool      `json:"email_marketing"`
	UserData
	// MFA contains attributes related to a user's MFA settings. Use [UserMFA.Enabled] to
	// check if MFA is active for the user.
	//
	// NOTE: MFA is available as a cloud-only feature and must be ignored in community.
	MFA         UserMFA         `json:"mfa"`
	Preferences UserPreferences `json:"preferences"`
	Password    UserPassword    `json:"-"`
	// Admin indicates whether the user has administrative privileges.
	Admin bool `json:"admin"`
	// AwaitingApproval marks a provisioned account that a namespace admin created but a system
	// admin has not approved yet. While true the account is inert: only an admin can mint its
	// activation link. It is set false when an admin creates the account directly or approves it.
	AwaitingApproval bool `json:"awaiting_approval"`
}

type UserAuthIdentifier string

type UserAuthMethod string

type UserAuthResponse struct {
	Token         string           `json:"token"`
	User          string           `json:"user"`
	Origin        string           `json:"origin"`
	AuthMethods   []UserAuthMethod `json:"auth_methods"`
	Name          string           `json:"name"`
	ID            string           `json:"id"`
	Tenant        *string          `json:"tenant"`
	Email         string           `json:"email"`
	RecoveryEmail string           `json:"recovery_email"`
	Role          *authorizer.Role `json:"role"`
	MFA           bool             `json:"mfa"`
	MaxNamespaces int              `json:"max_namespaces"`
	Admin         bool             `json:"admin"`
}

type UserData struct {
	Name     string `json:"name" validate:"required,name"`
	Username string `json:"username" validate:"required,username"`
	Email    string `json:"email" validate:"required,email"`
	// RecoveryEmail is a custom, non-unique email address that a user can use to recover their account
	// when they lose access to all other methods. It must never be equal to [UserData.Email].
	//
	// NOTE: Recovery email is available as a cloud-only feature and must be ignored in community.
	RecoveryEmail string `json:"recovery_email" validate:"omitempty,email"`
}

type UserInfo struct {
	// OwnedNamespaces are the namespaces where the user is the owner.
	OwnedNamespaces []Namespace
	// AssociatedNamespaces are the namespaces where the user is a member.
	AssociatedNamespaces []Namespace
}

type UserInvitation struct {
	ID          string               `json:"id"`
	Email       string               `json:"email"`
	CreatedAt   time.Time            `json:"created_at"`
	UpdatedAt   time.Time            `json:"updated_at"`
	Invitations int                  `json:"invitations"`
	Status      UserInvitationStatus `json:"status"`
}

type UserInvitationStatus string

type UserMFA struct {
	// Enabled reports whether MFA is enabled for the user.
	Enabled bool `json:"enabled"`
	// Secret is the key used for authenticating with the OTP server.
	Secret string `json:"-"`
	// RecoveryCodes are recovery tokens that the user can use to regain account access if they lose their MFA device.
	RecoveryCodes []string `json:"-"`
}

type UserOrigin string

type UserPassword struct {
	// Plain contains the plain text password.
	Plain string `json:"password" validate:"required,password"`
	// Hash contains the hashed pasword from plain text.
	Hash string `json:"-"`
}

type UserPreferences struct {
	// PreferredNamespace represents the namespace the user most recently authenticated with.
	PreferredNamespace string `json:"-"`

	// AuthMethods indicates the authentication methods that the user can use to authenticate.
	AuthMethods []UserAuthMethod `json:"auth_methods"`
}

type UserStatus string

type UserTokenRecover struct {
	Token     string    `json:"uid"`
	User      string    `json:"user_id"`
	CreatedAt time.Time `json:"created_at"`
}

type Username struct {
	ID string
}

type WebEndpoint struct {
	Address   string         `json:"address"`
	Namespace string         `json:"namespace"`
	DeviceUID string         `json:"device_uid"`
	Host      string         `json:"host"`
	Port      int            `json:"port"`
	TLS       WebEndpointTLS `json:"tls"`
}

type WebEndpointTLS struct {
	Enabled bool `json:"enabled"`
	Verify  bool `json:"verify"`
	// Domain doubles as the Host header override and, with TLS enabled, the SNI
	// sent during the handshake.
	Domain string `json:"domain"`
}