httpapi

package
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 30, 2026 License: Apache-2.0 Imports: 32 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func PrincipalFromContext 

func PrincipalFromContext(ctx context.Context) *identity.Principal

PrincipalFromContext retrieves the verified Principal that requireAuth stored in the request context. Returns nil when no principal is present (i.e. the authenticator was not configured or the middleware was not applied).

Types

type AgentReader 

type AgentReader interface {
	GetByID(ctx context.Context, id string) (*agent.Agent, error)
}

AgentReader is the agent repository subset needed for introspection.

type ControlAuditReadService 

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

ControlAuditReadService satisfies the controlAuditService interface by delegating to a controlaudit.Repository.

func NewControlAuditReadService 

func NewControlAuditReadService(repo controlaudit.Repository) *ControlAuditReadService

NewControlAuditReadService constructs a ControlAuditReadService. repo must be non-nil.

func (*ControlAuditReadService) ListAudit 

func (s *ControlAuditReadService) ListAudit(ctx context.Context, f controlaudit.ListFilter) ([]*controlaudit.ControlAuditRecord, error)

ListAudit returns control-plane audit records matching the filter, newest first.

type GrantReader 

type GrantReader interface {
	FindByID(ctx context.Context, id string) (*authority.AuthorityGrant, error)
	ListByAgent(ctx context.Context, agentID string) ([]*authority.AuthorityGrant, error)
	ListByProfile(ctx context.Context, profileID string) ([]*authority.AuthorityGrant, error)
}

GrantReader is the grant repository subset needed for introspection.

type ImpactSummary 

type ImpactSummary struct {
	ProfileCount       int
	GrantCount         int
	AgentCount         int
	ActiveProfileCount int
	ActiveGrantCount   int
	ActiveAgentCount   int
}

ImpactSummary holds aggregate counts for a surface's dependency graph. Computed by GetSurfaceImpact in the service layer, not the HTTP handler.

type IntrospectionService 

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

IntrospectionService satisfies the introspectionService interface by delegating to the underlying repository implementations.

func NewIntrospectionService 

func NewIntrospectionService(surfaces SurfaceReader, profiles ProfileReader) *IntrospectionService

NewIntrospectionService constructs an IntrospectionService with surface and profile readers. Use NewIntrospectionServiceFull to also enable agent and grant endpoints.

func NewIntrospectionServiceFull 

func NewIntrospectionServiceFull(surfaces SurfaceReader, profiles ProfileReader, agents AgentReader, grants GrantReader) *IntrospectionService

NewIntrospectionServiceFull constructs an IntrospectionService with all readers wired. All parameters must be non-nil.

func (*IntrospectionService) GetAgent 

func (s *IntrospectionService) GetAgent(ctx context.Context, id string) (*agent.Agent, error)

GetAgent returns an agent by ID. Returns nil, nil when the agent does not exist.

func (*IntrospectionService) GetGrant 

func (s *IntrospectionService) GetGrant(ctx context.Context, id string) (*authority.AuthorityGrant, error)

GetGrant returns a single grant by its ID. Returns nil, nil when the grant does not exist.

func (*IntrospectionService) GetProfile 

func (s *IntrospectionService) GetProfile(ctx context.Context, id string) (*authority.AuthorityProfile, error)

GetProfile returns the latest version of a profile by its logical ID. Returns nil, nil when the profile does not exist.

func (*IntrospectionService) GetProfileRecovery 

func (s *IntrospectionService) GetProfileRecovery(ctx context.Context, id string) (*ProfileRecoveryResult, error)

GetProfileRecovery computes a read-only recovery analysis for the given profile ID. Returns nil, nil when the profile does not exist.

func (*IntrospectionService) GetSurface 

func (s *IntrospectionService) GetSurface(ctx context.Context, id string) (*surface.DecisionSurface, error)

GetSurface returns the latest persisted version of a surface. Returns nil, nil when the surface does not exist.

func (*IntrospectionService) GetSurfaceImpact 

func (s *IntrospectionService) GetSurfaceImpact(ctx context.Context, surfaceID string) (*SurfaceImpactResult, error)

GetSurfaceImpact assembles the full dependency graph for a decision surface: profiles referencing the surface → grants referencing those profiles → distinct agents referenced by those grants. Returns nil, nil when the surface does not exist.

Ordering guarantees:

  • Profiles: sorted by ID ascending
  • Grants: sorted by ID ascending (all profiles combined, not grouped)
  • Agents: deduplicated by ID, sorted by ID ascending

Summary counts are computed in the service layer. Warnings are deterministic, emitted in a fixed order based on active-count thresholds only.

If the grants or agents readers are nil (partial wiring), grants and agents are returned as empty slices with a zero summary — the surface and profiles sections are still populated.

func (*IntrospectionService) GetSurfaceRecovery 

func (s *IntrospectionService) GetSurfaceRecovery(ctx context.Context, id string) (*SurfaceRecoveryResult, error)

GetSurfaceRecovery computes a read-only recovery analysis for the given surface ID. Returns nil, nil when the surface does not exist.

func (*IntrospectionService) ListGrantsByAgent 

func (s *IntrospectionService) ListGrantsByAgent(ctx context.Context, agentID string) ([]*authority.AuthorityGrant, error)

ListGrantsByAgent returns all grants for the given agent ID.

func (*IntrospectionService) ListGrantsByProfile 

func (s *IntrospectionService) ListGrantsByProfile(ctx context.Context, profileID string) ([]*authority.AuthorityGrant, error)

ListGrantsByProfile returns all grants for the given profile ID.

func (*IntrospectionService) ListProfileVersions 

func (s *IntrospectionService) ListProfileVersions(ctx context.Context, id string) ([]*authority.AuthorityProfile, error)

ListProfileVersions returns all versions of a profile ordered by version descending (latest first). Returns an empty slice when no profile with that logical ID exists.

func (*IntrospectionService) ListProfilesBySurface 

func (s *IntrospectionService) ListProfilesBySurface(ctx context.Context, surfaceID string) ([]*authority.AuthorityProfile, error)

ListProfilesBySurface returns all profiles for the given surface. Returns an empty slice when no profiles are attached.

func (*IntrospectionService) ListSurfaceVersions 

func (s *IntrospectionService) ListSurfaceVersions(ctx context.Context, id string) ([]*surface.DecisionSurface, error)

ListSurfaceVersions returns all versions of a surface in ascending version order. Returns an empty slice when the surface does not exist.

type ProfileReader 

type ProfileReader interface {
	FindByID(ctx context.Context, id string) (*authority.AuthorityProfile, error)
	ListBySurface(ctx context.Context, surfaceID string) ([]*authority.AuthorityProfile, error)
	ListVersions(ctx context.Context, id string) ([]*authority.AuthorityProfile, error)
}

ProfileReader is the profile repository subset needed for introspection.

type ProfileRecoveryResult 

type ProfileRecoveryResult struct {
	ProfileID     string `json:"profile_id"`
	SurfaceID     string `json:"surface_id"`
	LatestVersion int    `json:"latest_version"`
	LatestStatus  string `json:"latest_status"`
	// ActiveVersion is nil when no version is currently effective (e.g. future effective_date).
	ActiveVersion *int                  `json:"active_version"`
	ActiveStatus  *string               `json:"active_status"`
	VersionCount  int                   `json:"version_count"`
	Versions      []ProfileVersionEntry `json:"versions"`
	// ActiveGrantCount is the number of active grants linked to this profile.
	// -1 means the grant repository is not available.
	ActiveGrantCount int `json:"active_grant_count"`
	// CapabilityNote is an honest description of the current profile lifecycle behaviour.
	CapabilityNote         string   `json:"capability_note"`
	Warnings               []string `json:"warnings"`
	RecommendedNextActions []string `json:"recommended_next_actions"`
}

ProfileRecoveryResult is the assembled recovery analysis for an authority profile. It is read-only — computed from persisted state, no writes occur.

type ProfileVersionEntry 

type ProfileVersionEntry struct {
	Version       int       `json:"version"`
	Status        string    `json:"status"`
	EffectiveFrom time.Time `json:"effective_from"`
}

ProfileVersionEntry is one row in the profile recovery versions list.

type Server 

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

func NewServer 

func NewServer(orchestrator orchestrator) *Server

func NewServerFull 

func NewServerFull(
	orch orchestrator,
	controlPlane controlPlaneService,
	approvalSvc approvalService,
	introspectionSvc introspectionService,
	controlAuditSvc controlAuditService,
	grantSvc grantLifecycleService,
) *Server

NewServerFull constructs a Server with all services including the control-plane audit and grant lifecycle services. Any service may be nil; its endpoints will return 501 Not Implemented.

func NewServerWithAllServices 

func NewServerWithAllServices(
	orch orchestrator,
	controlPlane controlPlaneService,
	approvalSvc approvalService,
	introspectionSvc introspectionService,
) *Server

NewServerWithAllServices constructs a Server with all optional services wired in. Any service may be nil; its endpoints will return 501 Not Implemented.

func NewServerWithControlPlane 

func NewServerWithControlPlane(orchestrator orchestrator, controlPlane controlPlaneService) *Server

func NewServerWithServices 

func NewServerWithServices(orchestrator orchestrator, controlPlane controlPlaneService, approvalSvc approvalService) *Server

func (*Server) ListenAndServe 

func (s *Server) ListenAndServe(addr string) error

func (*Server) ServeHTTP 

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Server) WithAuthMode 

func (s *Server) WithAuthMode(mode config.AuthMode) *Server

WithAuthMode sets the authentication mode for the server. Must always be called at startup with the value from config (cfg.Auth.Mode). config.AuthModeOpen — requests pass through without authentication. config.AuthModeRequired — all governed routes require a valid bearer token.

func (*Server) WithAuthenticator 

func (s *Server) WithAuthenticator(a auth.Authenticator) *Server

WithAuthenticator configures the server to authenticate governance requests. It is safe to call after NewServerFull because requireAuth reads s.authenticator at request time rather than at route-registration time. Returns the server to allow builder-style chaining.

func (*Server) WithDemoSeeded 

func (s *Server) WithDemoSeeded(seeded bool) *Server

WithDemoSeeded records whether demo data was successfully seeded at startup, so the Explorer config endpoint can tell the UI which scenarios are ready.

func (*Server) WithExplorerEnabled 

func (s *Server) WithExplorerEnabled(enabled bool) *Server

WithExplorerEnabled registers the /explorer routes when enabled is true. Call this at startup with cfg.Server.ExplorerEnabled after NewServerFull. When false (or never called) the explorer routes are not registered and requests to /explorer return 404.

When WithLocalIAM has been called, Explorer POST routes use session-cookie auth (via the localiam AuthMiddleware). Otherwise they fall back to the existing bearer-token requireAuth/requireRole path unchanged.

func (*Server) WithHealthCheck 

func (s *Server) WithHealthCheck(fn func(context.Context) error) *Server

WithHealthCheck sets a function that handleReady calls to verify the backing store is reachable. Return nil means ready; any error causes /readyz to respond 503. Pass nil to treat the server as always ready (memory mode).

func (*Server) WithLocalIAM 

func (s *Server) WithLocalIAM(svc *localiam.Service) *Server

WithLocalIAM enables local platform IAM (username/password login for the Explorer/console). It registers the /auth/* endpoints and wires the session authenticator. Call before WithExplorerEnabled to ensure session auth is applied to Explorer routes; calling order is otherwise flexible because Explorer route handlers check s.localIAM at request time.

The /v1/* routes and StaticTokenAuthenticator are not affected.

func (*Server) WithOIDC 

func (s *Server) WithOIDC(svc oidcProvider, secureCookies bool) *Server

WithOIDC enables OIDC-based platform login. It registers /auth/oidc/login and /auth/oidc/callback. WithLocalIAM must be called first because session creation is delegated to the local IAM service.

secureCookies should match cfg.LocalIAM.SecureCookies so that the OIDC helper cookies (state, PKCE) use the same Secure flag as the session cookie.

The /v1/* routes and StaticTokenAuthenticator are not affected.

func (*Server) WithPolicyMeta 

func (s *Server) WithPolicyMeta(mode, evaluatorName string) *Server

WithPolicyMeta attaches policy mode metadata to the server for use in health and evaluate responses. Call this at boot after detecting the active evaluator. mode is a short string like "noop"; evaluatorName is a human-readable label.

func (*Server) WithStoreBackend 

func (s *Server) WithStoreBackend(backend string) *Server

WithStoreBackend records the active store backend (e.g. "memory", "postgres") so the Explorer config endpoint can surface it to the UI.

type SurfaceImpactResult 

type SurfaceImpactResult struct {
	Surface  *surface.DecisionSurface
	Profiles []*authority.AuthorityProfile // sorted by ID ascending
	Grants   []*authority.AuthorityGrant   // sorted by ID ascending; one row per grant across all profiles
	Agents   []*agent.Agent                // deduplicated, sorted by ID ascending
	Summary  ImpactSummary
	Warnings []string
}

SurfaceImpactResult is the assembled dependency analysis for a decision surface: the surface itself, all profiles referencing it, all grants referencing those profiles, and the distinct agents referenced by those grants. Ordering is stable: profiles, grants, and agents are sorted by ID ascending. Warnings are deterministic, based only on active-count thresholds.

type SurfaceReader 

type SurfaceReader interface {
	FindLatestByID(ctx context.Context, id string) (*surface.DecisionSurface, error)
	ListVersions(ctx context.Context, id string) ([]*surface.DecisionSurface, error)
}

SurfaceReader is the surface repository subset needed for introspection.

type SurfaceRecoveryResult 

type SurfaceRecoveryResult struct {
	SurfaceID              string   `json:"surface_id"`
	LatestVersion          int      `json:"latest_version"`
	LatestStatus           string   `json:"latest_status"`
	ActiveVersion          *int     `json:"active_version"` // null when no active version exists
	ActiveStatus           *string  `json:"active_status"`  // null when no active version exists
	SuccessorSurfaceID     string   `json:"successor_surface_id"`
	DeprecationReason      string   `json:"deprecation_reason"`
	VersionCount           int      `json:"version_count"`
	Warnings               []string `json:"warnings"`
	RecommendedNextActions []string `json:"recommended_next_actions"`
}

SurfaceRecoveryResult is the assembled recovery analysis for a decision surface. It is read-only — computed from persisted state, no writes occur.

Fields use *int / *string for version/status pairs so the caller can distinguish "no active version" (nil) from "version 0" or "".

type SurfaceVersionSummary 

type SurfaceVersionSummary struct {
	Version       int       `json:"version"`
	Status        string    `json:"status"`
	EffectiveFrom time.Time `json:"effective_from"`
}

SurfaceVersionSummary is a compact version entry used in the profile recovery response.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.