restapi

type AcceptedClaim struct {
	Group    string `json:"group,omitempty"`
	Resource string `json:"resource"`
}

type AcceptedHubAccess struct {
	Capability string `json:"capability"`
	Scope      string `json:"scope"`
}

type CreateOrgRequest struct {
	DisplayName          string `json:"displayName"`
	WorkspaceCreation    string `json:"workspaceCreation,omitempty"`    // "members" | "admin"; default "members"
	CatalogEntryCreation string `json:"catalogEntryCreation,omitempty"` // "members" | "admin"; default "admin"
}

type CreateWorkspaceRequest struct {
	DisplayName string `json:"displayName"`
}

type EdgeInstallTargetView struct {
	Workspace            string `json:"workspace"`
	WorkspaceDisplayName string `json:"workspaceDisplayName,omitempty"`
	Name                 string `json:"name"`
	// Eligible is the single field the UI should gate on. It is Connected
	// today, named separately so tightening the rule later (agent version
	// floor, say) does not require every caller to learn the new condition.
	Eligible     bool   `json:"eligible"`
	Connected    bool   `json:"connected"`
	Phase        string `json:"phase,omitempty"`
	AgentVersion string `json:"agentVersion,omitempty"`
}

type EdgeTargetRef struct {
	// Workspace is the team workspace UUID the edge lives in.
	Workspace string `json:"workspace"`
	// Name is the KubernetesCluster's name.
	Name string `json:"name"`
}

type EnableProviderRequest struct {
	AcceptedClaims []AcceptedClaim `json:"acceptedClaims"`
	// AcceptedHubAccess lists the hub capabilities (CatalogEntry.spec.hubAccess)
	// the user accepted. Each must be declared by the provider. Accepting an
	// org-scoped capability requires an org admin; a workspace-scoped one, an
	// admin of this workspace or of the org. Omitted capabilities are not
	// granted, and the decision is recorded either way.
	AcceptedHubAccess []AcceptedHubAccess `json:"acceptedHubAccess,omitempty"`
}

type EnableProviderResponse struct {
	BindingName string `json:"bindingName"`
	// HubAccess is what was granted, when the provider declares any.
	HubAccess []AcceptedHubAccess `json:"hubAccess,omitempty"`
}

type EnabledProviderDetail struct {
	BindingName string `json:"bindingName"`
	// ExportPath is the workspace path of the bound APIExport.
	ExportPath string `json:"exportPath"`
	// SelfHosted is true when the binding targets the Org's own provider
	// instance rather than the platform's.
	SelfHosted bool `json:"selfHosted"`
	// StaleClaims lists claims this provider still pins to a different copy of
	// a dependency than this workspace binds — the state a provider lands in
	// when that dependency is swapped underneath it. kcp reports such a binding
	// as healthy while serving none of the claimed resources, so this is the
	// only place the condition is visible before a downstream 404.
	StaleClaims []StaleClaim `json:"staleClaims,omitempty"`
	// Terminating is true when the provider has been disabled but kcp is still
	// cascade-deleting the bound APIs' resources. The binding (and the
	// provider's API surface) remains live until that finishes, so the portal
	// must render this as "disabling", not as enabled or disabled.
	Terminating bool `json:"terminating,omitempty"`
	// HubAccess reports the provider's hub capabilities in this workspace:
	// which are in force and which it declares but nobody accepted yet.
	// Absent when the provider declares none.
	HubAccess *HubAccessState `json:"hubAccess,omitempty"`
	// DeletionBlocked is kcp's explanation of what is holding a terminating
	// binding open — e.g. "Some content in the workspace has finalizers
	// remaining: <finalizer> in 3 resource instances". A binding in this state
	// never finishes disabling on its own; whoever owns the named finalizer has
	// to act, and this message is the only place the user learns that.
	DeletionBlocked string `json:"deletionBlocked,omitempty"`
}

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

type HubAccessState struct {
	// Granted are the capabilities in force (declared and accepted).
	Granted []AcceptedHubAccess `json:"granted,omitempty"`
	// Pending are declared capabilities nobody has accepted: new in the
	// provider's catalog entry, or declined. Re-enabling offers them again.
	Pending []AcceptedHubAccess `json:"pending,omitempty"`
	// Implicit is true when at least one granted capability is in force only
	// through the platform default (nobody entitled to decide it has yet).
	Implicit bool `json:"implicit,omitempty"`
}

type KubeconfigConfig struct {
	HubExternalURL string
	DevMode        bool
	OIDCIssuerURL  string
	OIDCClientID   string
}

type ListAppAccessGrantsResponse struct {
	Items []kcp.AppAccessGrant `json:"items"`
}

type ListEdgeInstallTargetsResponse struct {
	Items []EdgeInstallTargetView `json:"items"`
	// Eligible is true when at least one item is.
	Eligible bool `json:"eligible"`
	// Reason is human-readable and empty when Eligible.
	Reason string `json:"reason,omitempty"`
}

type ListEnabledProvidersResponse struct {
	BindingNamesByProvider map[string]string                `json:"bindingNamesByProvider"`
	BindingsByProvider     map[string]EnabledProviderDetail `json:"bindingsByProvider"`
}

type ListResponse[T any] struct {
	Items []T `json:"items"`
}

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

type MembershipAddRequest struct {
	User string `json:"user"`
	Role string `json:"role"` // admin | member
	// Invite pre-provisions a pending User when the identifier is an email
	// with no matching account. The pending User carries the email-derived
	// RBAC identity immediately (so memberships and app grants written now
	// apply on arrival) and is adopted by the first OIDC sign-in with that
	// email. Without this flag an unknown identifier stays a clean 404 so
	// typos cannot mint ghost users.
	Invite bool `json:"invite,omitempty"`
}

type MembershipPatchRequest struct {
	Role string `json:"role"`
}

type MembershipView struct {
	User string `json:"user"`
	// RBACIdentity is the member's kcp username (User.Spec.RBACIdentity,
	// "railgrid:<email>") — the subject string every tenant-workspace RBAC
	// binding uses. Consumers writing RBAC (e.g. App Studio's app-access
	// grants) must bind this, never the User CR name.
	RBACIdentity string `json:"rbacIdentity,omitempty"`
	// Email / UserDisplayName label the member as a person — `user` is the
	// CR name (e.g. "static-user-47b9dce0e91570a1", "user-x2f9…"), which is
	// meaningless in a member list. Best-effort: pending invites may have
	// only an email; some accounts may have neither.
	Email                string `json:"email,omitempty"`
	UserDisplayName      string `json:"userDisplayName,omitempty"`
	Role                 string `json:"role"`
	OrgUUID              string `json:"orgUUID"`
	WorkspaceUUID        string `json:"workspaceUUID,omitempty"`
	OrgDisplayName       string `json:"orgDisplayName,omitempty"`
	WorkspaceDisplayName string `json:"workspaceDisplayName,omitempty"`
}

type OrgProviderOps interface {
	EnsureOrgProviderWorkspace(ctx context.Context, orgUUID, name string) (string, error)
	ListOrgProviderWorkspaces(ctx context.Context, orgUUID string) ([]kcp.OrgProviderWorkspace, error)
	GetOrgProviderWorkspace(ctx context.Context, orgUUID, name string) (*kcp.OrgProviderWorkspace, error)
	DeleteOrgProviderWorkspace(ctx context.Context, orgUUID, name string) error
	ListEdgeInstallTargets(ctx context.Context, orgUUID string) ([]kcp.EdgeInstallTarget, error)
	GetEdgeInstallTarget(ctx context.Context, orgUUID, wsUUID, name string) (*kcp.EdgeInstallTarget, error)

	// RecordProviderEdgeBinding stamps the chosen edge onto the provider
	// Workspace at registration. The backend proxy reads it back to route this
	// provider's data plane over the tunnel, so it must live somewhere only the
	// hub writes — not on the tenant-authored CatalogEntry.
	RecordProviderEdgeBinding(ctx context.Context, orgUUID, providerName, wsUUID, edgeName string) error
}

type OrgProviderView struct {
	Name string `json:"name"`
	// WorkspacePath is where the Org installs its provider chart.
	WorkspacePath string `json:"workspacePath"`
	// ClusterName is the logical cluster ID of that workspace.
	ClusterName string `json:"clusterName,omitempty"`
	// Phase is the kcp workspace phase (e.g. "Ready").
	Phase string `json:"phase,omitempty"`
	// Registered is true once the provider's chart has run its `init` and
	// self-registered a CatalogEntry the hub can see. Until then the workspace
	// exists but the provider is not installable by any Workspace.
	Registered bool `json:"registered"`
	// DisplayName / Description / Version / APIExportName mirror the
	// CatalogEntry once Registered; empty before that.
	DisplayName   string `json:"displayName,omitempty"`
	Description   string `json:"description,omitempty"`
	Version       string `json:"version,omitempty"`
	APIExportName string `json:"apiExportName,omitempty"`
	Ready         bool   `json:"ready"`

	// InstalledVersion is the version the Org's copy is running, and
	// AvailableVersion is what the platform's copy of the same provider runs
	// now — the pair the upgrade verdict compared. Chart versions from the
	// selfHosting recipe when both sides carry one; otherwise the entries'
	// spec.version, because not every provider stamps a chart version — the
	// infrastructure operator registers from its embedded manifest, which has
	// no chart to read one from. AvailableVersion is empty when the provider
	// has no installable platform counterpart (an Org-authored provider).
	InstalledVersion string `json:"installedVersion,omitempty"`
	AvailableVersion string `json:"availableVersion,omitempty"`
	// UpgradeAvailable is true when the installed and available versions are
	// both known and differ. The hub owns the comparison so the portal cannot
	// drift from however "needs an upgrade" is defined later.
	UpgradeAvailable bool `json:"upgradeAvailable,omitempty"`
}

type OrgView struct {
	UUID                 string     `json:"uuid"`
	DisplayName          string     `json:"displayName"`
	Personal             bool       `json:"personal"`
	WorkspaceCreation    string     `json:"workspaceCreation"`
	CatalogEntryCreation string     `json:"catalogEntryCreation"`
	WorkspaceQuota       int32      `json:"workspaceQuota,omitempty"`
	CreatedAt            time.Time  `json:"createdAt"`
	DeletionRequestedAt  *time.Time `json:"deletionRequestedAt,omitempty"`
	// Role is the CALLER's org-scope role ("admin" | "member") — what the
	// tenant middleware will resolve for org-scope requests. The portal
	// uses it to hide admin-only controls (member management, rename,
	// delete) instead of rendering buttons that can only 403.
	Role string `json:"role,omitempty"`
}

type PatchOrgRequest struct {
	DisplayName          string `json:"displayName,omitempty"`
	WorkspaceCreation    string `json:"workspaceCreation,omitempty"`
	CatalogEntryCreation string `json:"catalogEntryCreation,omitempty"`
	WorkspaceQuota       *int32 `json:"workspaceQuota,omitempty"`
}

type PatchWorkspaceRequest struct {
	DisplayName string `json:"displayName,omitempty"`
}

type ProviderCredentialMinter interface {
	EnsureProviderSAAtPath(ctx context.Context, workspacePath string) error
	MintProviderKubeconfigAtPath(ctx context.Context, workspacePath, hubExternalURL string) ([]byte, error)
	// RotateProviderCredentialAtPath issues a NEW token for the same
	// ServiceAccount and retires the previous one after a grace period.
	RotateProviderCredentialAtPath(ctx context.Context, workspacePath, providerName, hubExternalURL string) (*providers.RotatedCredential, error)
}

type ProviderLookup interface {
	Get(name string) (providers.Provider, bool)
	GetForOrg(orgUUID, name string) (providers.Provider, bool)
	ListForOrg(orgUUID string) []providers.Provider
}

type RegisterOrgProviderRequest struct {
	// Name identifies the provider within the Org. It becomes the workspace
	// name, the CatalogEntry name the provider's chart must use, and the
	// binding name in every Workspace that enables it.
	//
	// When self-hosting a platform provider, use that provider's name: the
	// chart registers its CatalogEntry under its own name, so anything else
	// would leave the workspace and the registered provider mismatched.
	Name string `json:"name"`

	// SourceProvider names the platform provider being self-hosted, when this
	// registration is "run your own copy of X" rather than "register something
	// I wrote". It selects whose published deployment recipe the returned
	// instructions are rendered from. Defaults to Name.
	SourceProvider string `json:"sourceProvider,omitempty"`

	// Edge names the cluster the provider will be installed into. Required:
	// the hub reaches an org-owned provider's backend over that edge's tunnel
	// and has no other route into a tenant cluster
	// (docs/byo-provider-edge-transport.md E-2).
	Edge *EdgeTargetRef `json:"edge,omitempty"`
}

type RegisterOrgProviderResponse struct {
	Provider OrgProviderView `json:"provider"`
	// Kubeconfig is the workspace-scoped credential, PEM-free YAML.
	Kubeconfig string `json:"kubeconfig"`
	// Instructions are the rendered install steps, present when the provider
	// being self-hosted publishes a deployment recipe. Nil for a provider the
	// Org wrote itself, which the Org already knows how to deploy.
	Instructions *providers.InstallInstructions `json:"instructions,omitempty"`
}

type RotateOrgProviderCredentialResponse struct {
	Provider OrgProviderView `json:"provider"`
	// Kubeconfig is the NEW credential. Shown exactly once, like registration.
	Kubeconfig string `json:"kubeconfig"`
	// PreviousValidUntil is when the credential this call replaced stops
	// working (RFC3339); empty when there was nothing to retire. It is the
	// deadline for reinstalling the chart with the new kubeconfig: until then
	// both tokens belong to the same ServiceAccount and the provider keeps
	// working on either.
	PreviousValidUntil string `json:"previousValidUntil,omitempty"`
	RotatedAt          string `json:"rotatedAt"`
	// Instructions are re-rendered alongside the credential — whoever rotates
	// is about to run the install commands again.
	Instructions *providers.InstallInstructions `json:"instructions,omitempty"`
}

type StaleClaim struct {
	// Group and Resource name the claimed resource, e.g.
	// "infrastructure.railgrid.ai" / "instances".
	Group    string `json:"group"`
	Resource string `json:"resource"`
	// BoundExportPath is the copy this workspace actually uses, and so the one
	// the provider would have to be repointed at.
	BoundExportPath string `json:"boundExportPath"`
	// ClaimedIdentity and BoundIdentity are the two hashes, truncated: enough
	// to tell them apart in a UI, and the full values are of no use to a reader
	// who cannot act on them anyway.
	ClaimedIdentity string `json:"claimedIdentity"`
	BoundIdentity   string `json:"boundIdentity"`
	// Repointable is true when the provider is self-hosted by this Org, in
	// which case re-enabling it repairs the pin. For a platform provider the
	// export is shared by every Org and re-enabling changes nothing, so the
	// portal must not offer that as the fix.
	Repointable bool `json:"repointable"`
}

type ValidationError struct{ Msg string }

type WorkspaceOps interface {
	// Org workspace lifecycle
	EnsureOrgWorkspace(ctx context.Context, orgUUID string) error

	// Org Membership CRUD (CRs in the Org workspace)
	EnsureOrgMembership(ctx context.Context, orgUUID, userName, role string) error
	ListOrgMemberships(ctx context.Context, orgUUID string) ([]string, error)
	GetOrgMembershipRole(ctx context.Context, orgUUID, userName string) (string, error)
	PatchOrgMembershipRole(ctx context.Context, orgUUID, userName, role string) error
	DeleteOrgMembership(ctx context.Context, orgUUID, userName string) error

	// Child Workspace lifecycle + projections
	EnsureChildWorkspace(ctx context.Context, orgUUID, wsUUID string) error
	EnsureChildWorkspaceRailgridBinding(ctx context.Context, orgUUID, wsUUID string) error
	EnsureChildWorkspaceDefaultMCPServer(ctx context.Context, orgUUID, wsUUID string) error
	// EnsureChildWorkspaceAdmin grants cluster-admin in the child team
	// Workspace to the given rbacIdentity. Idempotent. Used at workspace
	// create time and when adding a member, since the kcp-side CRB is
	// otherwise only seeded by the org bootstrap controller for the
	// user's default workspace — every other workspace would 403 from
	// the kcp proxy without this call.
	EnsureChildWorkspaceAdmin(ctx context.Context, orgUUID, wsUUID, rbacIdentity string) error
	// RevokeChildWorkspaceAdmin removes the rbacIdentity's cluster-admin
	// binding from the child team Workspace. Grants are per user, so this
	// never touches another member's access. Idempotent on NotFound.
	RevokeChildWorkspaceAdmin(ctx context.Context, orgUUID, wsUUID, rbacIdentity string) error
	// ListOrgMembershipRoles returns user name → role for every org-scope
	// Membership CR. Used to bind the Org's admins into a new child
	// workspace (O-15).
	ListOrgMembershipRoles(ctx context.Context, orgUUID string) (map[string]string, error)
	// ListChildTeamWorkspaces lists the Org's team workspaces, excluding
	// infrastructure children such as the `providers` container for org-owned
	// providers. Tenant-facing views must use this rather than the unfiltered
	// list: the container has no Memberships, so it would render as a workspace
	// row that 403s the moment a user selects it.
	ListChildTeamWorkspaces(ctx context.Context, orgUUID string) ([]string, error)
	GetWorkspaceDisplayName(ctx context.Context, orgUUID, wsUUID string) (string, error)
	SetWorkspaceDisplayName(ctx context.Context, orgUUID, wsUUID, displayName string) error
	GetWorkspaceDeletionRequestedAt(ctx context.Context, orgUUID, wsUUID string) (*time.Time, bool, error)
	SetWorkspaceDeletionAnnotation(ctx context.Context, orgUUID, wsUUID string, at time.Time) error
	ClearWorkspaceDeletionAnnotation(ctx context.Context, orgUUID, wsUUID string) error

	// GetChildWorkspaceClusterName returns the kcp logical-cluster name
	// (the /clusters/<name> hash) for a child workspace. Used to build
	// per-workspace kubeconfigs for the download endpoint.
	GetChildWorkspaceClusterName(ctx context.Context, orgUUID, wsUUID string) (string, error)

	// MCPServer CRUD in the tenant workspace. The in-core reconciler provisions
	// each server's identity; GetMCPServerToken follows status.tokenSecretRef
	// (empty string = not provisioned yet).
	ListMCPServers(ctx context.Context, clusterName string) ([]kcp.MCPServerInfo, error)
	CreateMCPServer(ctx context.Context, clusterName, name, displayName, instructions string, readOnly bool) error
	UpdateMCPServer(ctx context.Context, clusterName, name, displayName, instructions string, readOnly bool) error
	DeleteMCPServer(ctx context.Context, clusterName, name string) error
	GetMCPServerToken(ctx context.Context, clusterName, name string) (string, error)

	// EnsureProviderAPIBinding creates an APIBinding in the target
	// child workspace, owned by the hub's kcp-admin identity. Used by
	// the POST .../providers/{name}/enable handler — see
	// pkg/hub/kcp/bootstrap.go for the rationale (proxy's
	// defaultCluster pre-check would 403 any user attempt against a
	// non-default workspace, even with valid RBAC).
	EnsureProviderAPIBinding(ctx context.Context, orgUUID, wsUUID, bindingName, exportPath, exportName string, claims []kcp.ProviderClaim) error

	// ListProviderAPIBindings returns the set of provider APIBindings
	// (those referencing root:railgrid:providers:*) in the target
	// workspace, keyed by provider name. Used by the
	// GET .../providers/enabled handler so the portal can refresh the
	// "enabled providers" sidebar set on every workspace switch
	// without 403'ing through the kcp user-proxy.
	ListProviderAPIBindings(ctx context.Context, orgUUID, wsUUID string) (map[string]kcp.ProviderBinding, error)

	// StaleClaimIdentities reports, per provider bound in the workspace, any
	// permission claim still pinned to a different copy of a dependency than
	// the workspace binds — the state every dependent lands in when a provider
	// is swapped for a self-hosted one. kcp reports those bindings as healthy
	// while serving none of the claimed resources, so the portal warning fed
	// by this is the only sign before a downstream 404.
	StaleClaimIdentities(ctx context.Context, orgUUID, wsUUID string) (map[string][]kcp.ClaimIdentityMismatch, error)

	// DeleteProviderAPIBinding removes a provider APIBinding from the
	// target workspace. Used by the POST .../providers/{name}/disable
	// handler. NotFound is a no-op.
	DeleteProviderAPIBinding(ctx context.Context, orgUUID, wsUUID, bindingName string) error

	// EnsureProviderEdgeProxyGrant / RemoveProviderEdgeProxyGrant manage
	// the ClusterRole/ClusterRoleBinding pair that lets a provider's SA
	// (under its cluster-qualified identity) use the "proxy" verb on
	// edges in the tenant workspace. Applied on Enable when the provider
	// declares spec.edgeProxyAccess; removed on Disable.
	EnsureProviderEdgeProxyGrant(ctx context.Context, orgUUID, wsUUID, providerName, subject string) error
	RemoveProviderEdgeProxyGrant(ctx context.Context, orgUUID, wsUUID, providerName string) error

	// ListAppAccessGrants / RemoveAppAccessGrant surface the published-app
	// invitations (labeled ClusterRoleBindings, plain workspace RBAC) so
	// tenant settings can show and revoke them. See app_access.go.
	ListAppAccessGrants(ctx context.Context, orgUUID, wsUUID string) ([]kcp.AppAccessGrant, error)
	RemoveAppAccessGrant(ctx context.Context, orgUUID, wsUUID, bindingName string) error
}

type WorkspaceView struct {
	UUID                string     `json:"uuid"`
	OrgUUID             string     `json:"orgUUID"`
	DisplayName         string     `json:"displayName,omitempty"`
	ClusterName         string     `json:"clusterName,omitempty"`
	DeletionRequestedAt *time.Time `json:"deletionRequestedAt,omitempty"`
	// Role is the CALLER's workspace-scope role ("admin" | "member"), or
	// empty when they hold no workspace-scope row here (possible for org
	// admins, who can list every workspace but manage only those they are
	// workspace-admin in — the middleware matches exact (org, ws) rows).
	// The portal gates workspace-admin controls on it.
	Role string `json:"role,omitempty"`
}