api

type AssignGrantRequest struct {
	// GrantDefinitionID identifies the definition to instantiate — either its
	// uid or its slug, resolved the same way every other definition reference
	// is. A slug always resolves to the live version.
	GrantDefinitionID string    `json:"grant_definition_id" binding:"required"`
	UserID            uuid.UUID `json:"user_id" binding:"required"`
	DatabaseID        uuid.UUID `json:"database_id" binding:"required"`
	// StartsAt defaults to now. The window's *length* is the definition's
	// duration_seconds and is not negotiable here — that is part of the shape.
	StartsAt *time.Time `json:"starts_at"`
}

type ChangePasswordRequest struct {
	Username        string `json:"username"`
	CurrentPassword string `json:"current_password" binding:"required"`
	NewPassword     string `json:"new_password" binding:"required"`
}

type ConnectionInfo struct {
	DatabaseUID  uuid.UUID `json:"database_uid"`
	DatabaseName string    `json:"database_name"`
	Protocol     string    `json:"protocol"`
	Format       string    `json:"format"` // "uri" or "ez-connect"
	URL          string    `json:"url"`
}

type ConnectionTestResponse struct {
	OK            bool   `json:"ok"`
	Stage         string `json:"stage"`
	Code          string `json:"code"`
	Message       string `json:"message"`
	HostKeyPinned bool   `json:"host_key_pinned,omitempty"`
	KnownHostKey  string `json:"ssh_known_host_key,omitempty"`
	// CAPinned / LearnedCACert are the Kubernetes counterparts: whether this
	// check performed the TOFU pin, and the bundle in force afterwards. Public
	// challenge material, exactly like the host key.
	CAPinned         bool   `json:"k8s_ca_pinned,omitempty"`
	K8sLearnedCACert string `json:"k8s_learned_ca_cert,omitempty"`
	// Warnings are problems that did not fail the check but that the admin needs
	// to see: today, an Oracle row whose upstream service name is also claimed
	// by rows spelling their host differently. A check can be green and still
	// carry one — the row works, connecting by shared service name does not.
	Warnings   []ConnectionTestWarning `json:"warnings,omitempty"`
	DurationMs int64                   `json:"duration_ms"`
}

type ConnectionTestWarning struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

type CreateAPIKeyRequest struct {
	Name      string     `json:"name" binding:"required"`
	ExpiresAt *time.Time `json:"expires_at"`
}

type CreateAPIKeyResponse struct {
	ID                   uuid.UUID        `json:"id"`
	Name                 string           `json:"name"`
	Key                  string           `json:"key"` // Only returned once!
	KeyPrefix            string           `json:"key_prefix"`
	ExpiresAt            *time.Time       `json:"expires_at"`
	CreatedAt            time.Time        `json:"created_at"`
	Connections          []ConnectionInfo `json:"connections"`
	ConnectionsTruncated bool             `json:"connections_truncated"`
}

type CreateDatabaseRequest struct {
	Name              string     `json:"name" binding:"required"`
	Description       string     `json:"description"`
	Host              string     `json:"host" binding:"required"`
	Port              int        `json:"port"`
	DatabaseName      string     `json:"database_name"`
	Username          string     `json:"username" binding:"required"`
	Password          string     `json:"password"`
	SSLMode           string     `json:"ssl_mode"`
	Protocol          string     `json:"protocol"`
	OracleServiceName string     `json:"oracle_service_name"`
	MongoAuthSource   string     `json:"mongo_auth_source"`
	Listable          *bool      `json:"listable"`
	ViaUID            *uuid.UUID `json:"via_uid"`
	// SSH bastion secrets (write-only, never returned).
	SSHPrivateKey string `json:"ssh_private_key"`
	SSHPassphrase string `json:"ssh_passphrase"`
	// Kubernetes cluster material. The ServiceAccount bearer token is sent as
	// Password — it is the row's secret, encrypted exactly like a database
	// password — while the CA bundle and the namespace are public and stored
	// in clear. There is deliberately no kubeconfig field: EKS/GKE kubeconfigs
	// authenticate through exec credential plugins, which a server daemon
	// cannot run.
	//
	// K8sCACert is optional: a row that supplies none gets a trust-on-first-use
	// pin instead, learned on the first connect and stored separately. Pasting
	// the bundle remains the stronger setup — see docs/kubernetes.md.
	K8sCACert                string `json:"k8s_ca_cert"`
	K8sNamespace             string `json:"k8s_namespace"`
	K8sInsecureSkipTLSVerify bool   `json:"k8s_insecure_skip_tls_verify"`
	// AccessApproverUserGroupUIDs / QueryApproverUserGroupUIDs name the user
	// groups allowed to decide grant *requests* for this server and to release
	// approval *holds* on statements against it. Omitted or empty falls back to
	// the server groups this server belongs to, and then to admins.
	AccessApproverUserGroupUIDs []uuid.UUID `json:"access_approver_user_group_uids"`
	QueryApproverUserGroupUIDs  []uuid.UUID `json:"query_approver_user_group_uids"`
	// TestConnection asks the API to validate the row by actually dialing it
	// once created. Opt-in, and never fatal: the outcome comes back as a
	// connection_test object alongside the created server.
	TestConnection bool `json:"test_connection"`
}

type CreateGrantDefinitionRequest struct {
	Name string `json:"name" binding:"required"`
	// Slug is a stable, human-typeable, machine-friendly identifier for this
	// definition — mandatory at the API level. The server never generates
	// one; that's the frontend's job (derive-from-name until the operator
	// edits it manually), which keeps the API contract explicit for CLI and
	// agent callers.
	Slug                string   `json:"slug" binding:"required"`
	Description         string   `json:"description"`
	DurationSeconds     int64    `json:"duration_seconds" binding:"required"`
	Controls            []string `json:"controls"`
	MaxQueryCounts      *int64   `json:"max_query_counts"`
	MaxBytesTransferred *int64   `json:"max_bytes_transferred"`
	// Priority, when supplied, is stamped verbatim on every grant
	// materialized from this definition instead of the tier its controls
	// would earn. null/omitted — the normal case — leaves it auto.
	Priority *int16 `json:"priority"`
	// AutoApprove, when true, makes grant requests against this definition
	// skip the pending/admin-approval step and materialize the grant
	// instantly.
	AutoApprove bool `json:"auto_approve"`
	// UserGroupUIDs restricts the definition to members of these user groups.
	// Empty/omitted = every user, which is how every pre-scoping definition
	// keeps behaving.
	UserGroupUIDs []uuid.UUID `json:"user_group_uids"`
	// ServerGroupUIDs restricts the definition to the databases currently
	// belonging to these server groups. Empty/omitted = every database.
	ServerGroupUIDs []uuid.UUID `json:"server_group_uids"`
	// ApprovalPatterns are RE2 patterns that suspend a matching statement
	// until a second human approves it. Empty/omitted = no approval gating.
	// Compiled here so a bad pattern is a 400 rather than a runtime surprise
	// on the proxy hot path.
	ApprovalPatterns []string `json:"approval_patterns"`
	// SampleQueries are representative SQL statements saved alongside the
	// patterns to validate them against — a test bench for pattern
	// authoring. See POST /grant-definitions/validate-patterns.
	SampleQueries []string `json:"sample_queries"`
	// ApproverUserGroupUIDs lists the user groups whose members may resolve
	// those holds, in addition to admins. Empty/omitted = admins only.
	ApproverUserGroupUIDs []uuid.UUID `json:"approver_user_group_uids"`

	// RetiredDatabaseUIDs catches the removed per-database scope. It is not a
	// compatibility shim: server groups are a different entity, so there is
	// nothing to fold it onto, and silently dropping a scope restriction on
	// the floor would fail *open*. Its only job is to make the request a 400
	// that names the replacement — see validateDefinitionRequest.
	RetiredDatabaseUIDs []uuid.UUID `json:"database_uids"`

	// RetiredGroupUIDs / RetiredApproverGroupUIDs catch the pre-rename
	// spellings of UserGroupUIDs / ApproverUserGroupUIDs. Server groups made a
	// bare "group" ambiguous, so both fields were renamed; the old spellings
	// are refused rather than folded onto their replacements — silently
	// ignoring a scope restriction fails *open*. See errRetiredGroupUIDs /
	// errRetiredApproverGroupUIDs.
	RetiredGroupUIDs         []uuid.UUID `json:"group_uids"`
	RetiredApproverGroupUIDs []uuid.UUID `json:"approver_group_uids"`
}

type CreateGrantRequestRequest struct {
	// GrantDefinitionID identifies the definition being requested — either
	// its uid or its slug. Widened from uid-only to accept a slug too,
	// rather than adding a sibling field, since this is the one place the
	// API takes a bare definition reference as a request-body value (every
	// other reference is a path param, resolved the same uid-or-slug way).
	GrantDefinitionID string    `json:"grant_definition_id" binding:"required"`
	DatabaseID        uuid.UUID `json:"database_id" binding:"required"`
	Justification     string    `json:"justification"`
}

type CreateServerGroupRequest struct {
	Name        string `json:"name" binding:"required"`
	Description string `json:"description"`
	// MemberUIDs, when non-nil, replaces the group's membership. On create it
	// seeds it; on update a nil value leaves membership untouched.
	MemberUIDs []uuid.UUID `json:"member_uids"`
	// AccessApproverUserGroupUIDs / QueryApproverUserGroupUIDs are the
	// group-level fallback for the two approver kinds: they cover every member
	// server that names no approvers of its own. Several groups holding the same
	// server union. Empty means the group names nobody, which leaves the
	// decision to admins.
	//
	// Unlike member_uids these are written on every update, empty included —
	// clearing a list is a real policy change and has to be expressible.
	AccessApproverUserGroupUIDs []uuid.UUID `json:"access_approver_user_group_uids"`
	QueryApproverUserGroupUIDs  []uuid.UUID `json:"query_approver_user_group_uids"`
}

type CreateUserGroupRequest struct {
	Name        string `json:"name" binding:"required"`
	Description string `json:"description"`
	// MemberUIDs, when non-nil, replaces the group's membership. On create
	// it seeds it; on update a nil value leaves membership untouched.
	MemberUIDs []uuid.UUID `json:"member_uids"`
}

type CreateUserRequest struct {
	Username string   `json:"username" binding:"required"`
	Password string   `json:"password" binding:"required"`
	Roles    []string `json:"roles"`
}

type DatabaseLimitedResponse struct {
	UID         uuid.UUID `json:"uid"`
	Name        string    `json:"name"`
	Description string    `json:"description"`
}

type DatabaseResponse struct {
	UID               uuid.UUID  `json:"uid"`
	Name              string     `json:"name"`
	Description       string     `json:"description"`
	Host              string     `json:"host,omitempty"`
	Port              int        `json:"port,omitempty"`
	DatabaseName      string     `json:"database_name,omitempty"`
	Username          string     `json:"username,omitempty"`
	SSLMode           string     `json:"ssl_mode,omitempty"`
	Protocol          string     `json:"protocol,omitempty"`
	OracleServiceName string     `json:"oracle_service_name,omitempty"`
	MongoAuthSource   string     `json:"mongo_auth_source,omitempty"`
	Listable          bool       `json:"listable"`
	CreatedBy         *uuid.UUID `json:"created_by,omitempty"`
	ViaUID            *uuid.UUID `json:"via_uid,omitempty"`
	// SSHKnownHostKey is the TOFU-pinned bastion host key (read-only). Secrets
	// (private key, passphrase) are never returned.
	SSHKnownHostKey string `json:"ssh_known_host_key,omitempty"`
	// Kubernetes cluster material. Public: the CA bundle is challenge material
	// and the namespace is scope, so both round-trip. The ServiceAccount token
	// never does.
	K8sCACert string `json:"k8s_ca_cert,omitempty"`
	// K8sLearnedCACert is the bundle dbbat pinned itself on first connect, when
	// the row supplied none (read-only). Kept apart from K8sCACert so a client
	// can say which of the two is in force: a supplied bundle always wins.
	K8sLearnedCACert         string `json:"k8s_learned_ca_cert,omitempty"`
	K8sNamespace             string `json:"k8s_namespace,omitempty"`
	K8sInsecureSkipTLSVerify bool   `json:"k8s_insecure_skip_tls_verify,omitempty"`
	// The two approver lists. Always rendered, empty included: an empty list is
	// a meaningful state (fall back to the server groups, then to admins), so
	// omitting it would make "cleared" indistinguishable from "unknown".
	AccessApproverUserGroupUIDs []uuid.UUID `json:"access_approver_user_group_uids"`
	QueryApproverUserGroupUIDs  []uuid.UUID `json:"query_approver_user_group_uids"`
	// ConnectionTest is present only when the request set test_connection.
	ConnectionTest *ConnectionTestResponse `json:"connection_test,omitempty"`
	// OracleServiceNameConflict is present only on an Oracle row whose upstream
	// service name is also claimed by rows pointing at a different host:port —
	// a configuration that makes every connect arriving with the shared service
	// name fail ORA-12514 while each row on its own checks out.
	OracleServiceNameConflict *OracleServiceNameConflictResponse `json:"oracle_service_name_conflict,omitempty"`
}

type DenyGrantRequestRequest struct {
	Reason string `json:"reason"`
}

type DeviceAuthorizationRequest struct {
	ClientName string `json:"client_name"`
	ClientID   string `json:"client_id"`
}

type DeviceAuthorizationResponse struct {
	DeviceCode              string `json:"device_code"`
	UserCode                string `json:"user_code"`
	VerificationURI         string `json:"verification_uri"`
	VerificationURIComplete string `json:"verification_uri_complete"`
	ExpiresIn               int    `json:"expires_in"`
	Interval                int    `json:"interval"`
}

type DeviceConsentInfo struct {
	ClientName string    `json:"client_name"`
	UserCode   string    `json:"user_code"`
	Status     string    `json:"status"`
	ExpiresAt  time.Time `json:"expires_at"`
}

type DeviceConsentRequest struct {
	UserCode string `json:"user_code" binding:"required"`
	Approve  bool   `json:"approve"`
}

type DeviceTokenRequest struct {
	GrantType  string `json:"grant_type" binding:"required"`
	DeviceCode string `json:"device_code" binding:"required"`
	ClientID   string `json:"client_id"`
}

type DumpMetadata struct {
	Available bool  `json:"available"`
	SizeBytes int64 `json:"size_bytes"`
}

type ErrorBody struct {
	Code       ErrorCode `json:"code"`
	Message    string    `json:"message"`
	Detail     string    `json:"detail,omitempty"`
	RetryAfter int       `json:"retry_after,omitempty"`
}

type ErrorCode string

type GrantSummary struct {
	UID                     uuid.UUID `json:"uid"`
	Controls                []string  `json:"controls"`
	StartsAt                time.Time `json:"starts_at"`
	ExpiresAt               time.Time `json:"expires_at"`
	Revoked                 bool      `json:"revoked"`
	Priority                int16     `json:"priority"`
	GrantDefinitionID       uuid.UUID `json:"grant_definition_id"`
	GrantDefinitionName     string    `json:"grant_definition_name"`
	GrantDefinitionSlug     string    `json:"grant_definition_slug"`
	GrantDefinitionIsActive bool      `json:"grant_definition_is_active"`
}

type LoginExchangeRequest struct {
	Code string `json:"code" binding:"required"`
}

type LoginExchangeResponse struct {
	AccessToken string `json:"access_token"`
	TokenType   string `json:"token_type"`
}

type LoginRequest struct {
	Username string `json:"username" binding:"required"`
	Password string `json:"password" binding:"required"`
}

type LoginResponse struct {
	Token     string       `json:"token"`
	ExpiresAt string       `json:"expires_at"`
	User      UserResponse `json:"user"`
}

type MeResponse struct {
	UID                    string          `json:"uid"`
	Username               string          `json:"username"`
	Roles                  []string        `json:"roles"`
	PasswordChangeRequired bool            `json:"password_change_required"`
	Session                SessionResponse `json:"session"`
}

type OracleServiceNameConflictResponse struct {
	// ServiceName is the shared upstream `oracle_service_name`.
	ServiceName string `json:"service_name"`
	// Upstreams are the distinct `host:port` spellings in play, sorted.
	Upstreams []string `json:"upstreams"`
	// Servers are the rows claiming the service name, ordered by name.
	Servers []OracleServiceNameConflictServerResponse `json:"servers"`
	// Message is the ready-made operator-facing sentence, so every surface
	// (this API, the connectivity check, the proxy log) says the same thing.
	Message string `json:"message"`
}

type OracleServiceNameConflictServerResponse struct {
	UID  uuid.UUID `json:"uid"`
	Name string    `json:"name"`
	Host string    `json:"host"`
	Port int       `json:"port"`
}

type PatternValidationResult struct {
	Pattern string `json:"pattern"`
	// Error is the compile error message, present only when the pattern
	// failed to compile. This is exactly the error NewApprovalGate silently
	// swallows (with only a server-side warning log) when building the live
	// per-session gate — see approval.go — surfaced here instead of staying
	// invisible until a live statement fails to hold.
	Error string `json:"error,omitempty"`
}

type PreLoginPasswordChangeRequest struct {
	Username        string `json:"username" binding:"required"`
	CurrentPassword string `json:"current_password" binding:"required"`
	NewPassword     string `json:"new_password" binding:"required"`
}

type QueryValidationResult struct {
	Query      string `json:"query"`
	Normalized string `json:"normalized"`
	Matched    bool   `json:"matched"`
	// MatchedPattern is the source text of the first pattern that matched,
	// present only when Matched is true.
	MatchedPattern string `json:"matched_pattern,omitempty"`
}

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

type ResetPasswordRequest struct {
	NewPassword string `json:"new_password" binding:"required"`
}

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

type SessionResponse struct {
	ExpiresAt string `json:"expires_at"`
	CreatedAt string `json:"created_at"`
}

type UpdateDatabaseRequest struct {
	// Name renames the server, subject to the same slug rule creation enforces
	// (store.IsValidServerName). It is the one field clients actually type —
	// the PostgreSQL/MySQL/MongoDB database name, the Oracle SERVICE_NAME — so
	// a rename breaks every saved connection string using the old one, while
	// leaving already-authenticated sessions alone. Omitted (null) leaves it
	// unchanged; a name already taken, soft-deleted rows included, is a 409.
	Name              *string    `json:"name"`
	Description       *string    `json:"description"`
	Host              *string    `json:"host"`
	Port              *int       `json:"port"`
	DatabaseName      *string    `json:"database_name"`
	Username          *string    `json:"username"`
	Password          *string    `json:"password"`
	SSLMode           *string    `json:"ssl_mode"`
	Protocol          *string    `json:"protocol"`
	OracleServiceName *string    `json:"oracle_service_name"`
	MongoAuthSource   *string    `json:"mongo_auth_source"`
	Listable          *bool      `json:"listable"`
	ViaUID            *uuid.UUID `json:"via_uid"`
	// ClearViaUID, when true, removes the SSH tunnel (direct dial). Distinct
	// from an omitted via_uid, which leaves the tunnel unchanged.
	ClearViaUID bool `json:"clear_via_uid"`
	// SSH bastion secrets (write-only, never returned).
	SSHPrivateKey *string `json:"ssh_private_key"`
	SSHPassphrase *string `json:"ssh_passphrase"`
	// Kubernetes cluster material; see CreateDatabaseRequest. The bearer token
	// is rotated through Password like any other secret.
	K8sCACert                *string `json:"k8s_ca_cert"`
	K8sNamespace             *string `json:"k8s_namespace"`
	K8sInsecureSkipTLSVerify *bool   `json:"k8s_insecure_skip_tls_verify"`
	// K8sResetLearnedCACert forgets the TOFU-learned bundle so the next connect
	// pins afresh. It is the exit from a stale pin when the cluster's CA
	// rotated and you do not have the new bundle to paste; supplying a
	// non-empty k8s_ca_cert clears it too, since a supplied bundle supersedes
	// anything learned.
	K8sResetLearnedCACert bool `json:"k8s_reset_learned_ca_cert"`
	// AccessApproverUserGroupUIDs / QueryApproverUserGroupUIDs replace the
	// server's approver lists wholesale. Omitted (null) leaves them alone; an
	// explicit `[]` clears them, handing the decision back to the server groups
	// and then to admins. Effective immediately, for grant requests already
	// filed and statements already parked — see docs/approvals.md.
	AccessApproverUserGroupUIDs *[]uuid.UUID `json:"access_approver_user_group_uids"`
	QueryApproverUserGroupUIDs  *[]uuid.UUID `json:"query_approver_user_group_uids"`
	// TestConnection asks the API to validate the row by actually dialing it
	// once updated. Opt-in, and never fatal.
	TestConnection bool `json:"test_connection"`
}

type UpdateGrantDefinitionRequest struct {
	Name                     *string     `json:"name"`
	Slug                     *string     `json:"slug"`
	Description              *string     `json:"description"`
	DurationSeconds          *int64      `json:"duration_seconds"`
	Controls                 []string    `json:"controls"`
	MaxQueryCounts           *int64      `json:"max_query_counts"`
	ClearMaxQueryCounts      bool        `json:"clear_max_query_counts"`
	MaxBytesTransferred      *int64      `json:"max_bytes_transferred"`
	ClearMaxBytesTransferred bool        `json:"clear_max_bytes_transferred"`
	Priority                 *int16      `json:"priority"`
	ClearPriority            bool        `json:"clear_priority"`
	AutoApprove              *bool       `json:"auto_approve"`
	UserGroupUIDs            []uuid.UUID `json:"user_group_uids"`
	ServerGroupUIDs          []uuid.UUID `json:"server_group_uids"`
	ApprovalPatterns         []string    `json:"approval_patterns"`
	SampleQueries            []string    `json:"sample_queries"`
	ApproverUserGroupUIDs    []uuid.UUID `json:"approver_user_group_uids"`

	// RetiredDatabaseUIDs is refused rather than folded; see
	// CreateGrantDefinitionRequest.RetiredDatabaseUIDs.
	RetiredDatabaseUIDs []uuid.UUID `json:"database_uids"`

	// RetiredGroupUIDs / RetiredApproverGroupUIDs are refused rather than
	// folded; see CreateGrantDefinitionRequest.RetiredGroupUIDs.
	RetiredGroupUIDs         []uuid.UUID `json:"group_uids"`
	RetiredApproverGroupUIDs []uuid.UUID `json:"approver_group_uids"`
}

type UpdateServerGroupRequest = CreateServerGroupRequest

type UpdateUserGroupRequest = CreateUserGroupRequest

type UpdateUserRequest struct {
	Password *string  `json:"password"`
	Roles    []string `json:"roles"`
	// UserGroupUIDs, when non-nil, replaces the user's user-group memberships
	// wholesale. Admin-only, like Roles.
	UserGroupUIDs []uuid.UUID `json:"user_group_uids"`
	// RetiredGroupUIDs catches the pre-rename spelling of UserGroupUIDs. It
	// is refused rather than folded onto UserGroupUIDs — silently ignoring a
	// scope restriction fails *open*. See errRetiredGroupUIDs.
	RetiredGroupUIDs []uuid.UUID `json:"group_uids"`
}

type UserResponse struct {
	UID                    string   `json:"uid"`
	Username               string   `json:"username"`
	Roles                  []string `json:"roles"`
	PasswordChangeRequired bool     `json:"password_change_required"`
}

type ValidatePatternsRequest struct {
	// Patterns are the RE2 approval-pattern sources to test — typically a
	// grant definition's approval_patterns field, saved or still being
	// edited in the dialog.
	Patterns []string `json:"patterns"`
	// Queries are sample SQL statements to test the patterns against —
	// typically a definition's sample_queries field.
	Queries []string `json:"queries"`
}