api

package
v1.0.0-alpha.22 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2026 License: AGPL-3.0 Imports: 28 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var FullErrorInResponse = atomic.Bool{}

FullErrorInResponse attaches the unwrapped cause of an error to the response body under `details.parent`. It is a **test-only** aid: it turns an opaque "an unexpected error occurred" into the chain that produced it, which is what makes a red integration run diagnosable. Never enable it on a served instance — the chain carries internals (SQL, validation paths, wrapped library errors) that the client has no business seeing.

Functions

func OgenErrorHandler 

func OgenErrorHandler(_ context.Context, w http.ResponseWriter, _ *http.Request, err error)

OgenErrorHandler is a custom ogen ErrorHandler that maps ogen's structural errors (decode, validate, security) into the ErrorDetails wire format so all error responses are consistent regardless of where the error originates.

func WithRequestHostMiddleware 

func WithRequestHostMiddleware(next http.Handler) http.Handler

WithRequestHostMiddleware injects the effective request proto+host into the context so handlers can derive a WebAuthn RPID even when the browser omits the Origin header (same-origin fetches).

func WithScopeContext 

func WithScopeContext(ctx context.Context, scopeCtx ScopeContext) context.Context

func WithSessionStateNoStore 

func WithSessionStateNoStore(next http.Handler) http.Handler

WithSessionStateNoStore prevents any GET /sessions/me response from being stored. It wraps the generated server so the header is also present on security and decoding errors emitted before the operation handler runs.

Types

type Handler 

type Handler struct {
	// UnimplementedHandler is embedded to provide default "not implemented"
	// responses for all endpoints, so only implemented methods need to be defined.
	api.UnimplementedHandler
	// contains filtered or unexported fields
}

func NewHandler 

func NewHandler(
	flowService service.FlowService,
	authAttemptService service.AuthAttemptService,
	sessionService service.SessionService,
	projectService service.ProjectService,
	userService service.UserService,
	schemaService *service.SchemaService,
	flowDefinitionService service.FlowDefinitionService,
	teamService *service.TeamService,
	brandingService *service.BrandingService,
	environmentService *service.EnvironmentService,
	eventService *service.EventService,
	tokenService service.TokenService,
	keyService service.KeyService,
	claimService service.ClaimService,
	grantService *service.GrantService,
	pool *service.DB,
	platformProjectID string,
) *Handler

func (*Handler) BeginUserPasskeyRegistration 

func (h *Handler) BeginUserPasskeyRegistration(ctx context.Context, req *api.BeginUserPasskeyRegistrationRequest, params api.BeginUserPasskeyRegistrationParams) (api.BeginUserPasskeyRegistrationRes, error)

BeginUserPasskeyRegistration starts a management-plane enrollment ceremony. The between-steps state rides an internal auth attempt (ADR 056) the service orchestrates; it can never be read, handed off, or exchanged.

func (*Handler) CompleteClaim 

func (h *Handler) CompleteClaim(ctx context.Context, req *api.CompleteClaimRequest, params api.CompleteClaimParams) (api.CompleteClaimRes, error)

func (Handler) CreateAuthAttempt 

func (h Handler) CreateAuthAttempt(ctx context.Context, req *api.CreateAuthAttemptRequest) (api.CreateAuthAttemptRes, error)

func (*Handler) CreateBranding 

func (h *Handler) CreateBranding(ctx context.Context, req *api.Branding, params api.CreateBrandingParams) (api.CreateBrandingRes, error)

func (*Handler) CreateFlow 

func (h *Handler) CreateFlow(ctx context.Context, req *api.CreateFlowRequest) (api.CreateFlowRes, error)

func (Handler) CreateFlowDefinition 

func (h Handler) CreateFlowDefinition(ctx context.Context, req *api.CreateFlowDefinitionRequest) (api.CreateFlowDefinitionRes, error)

func (*Handler) CreateGrant 

func (h *Handler) CreateGrant(ctx context.Context, req *api.CreateGrantRequest, params api.CreateGrantParams) (api.CreateGrantRes, error)

func (Handler) CreateHandoff 

func (h Handler) CreateHandoff(ctx context.Context, params api.CreateHandoffParams) (api.CreateHandoffRes, error)

func (*Handler) CreateProject 

func (h *Handler) CreateProject(ctx context.Context, req *api.CreateProjectRequest) (api.CreateProjectRes, error)

func (*Handler) CreateSchema 

func (h *Handler) CreateSchema(ctx context.Context, req api.CreateSchemaReq, params api.CreateSchemaParams) (api.CreateSchemaRes, error)

func (Handler) CreateSession 

func (h Handler) CreateSession(ctx context.Context, req *api.CreateSessionRequest) (api.CreateSessionRes, error)

func (*Handler) CreateTeam 

func (h *Handler) CreateTeam(ctx context.Context, req *api.CreateTeamRequest, params api.CreateTeamParams) (r api.CreateTeamRes, _ error)

func (*Handler) CreateUser 

func (h *Handler) CreateUser(ctx context.Context, req *api.CreateUserRequest, params api.CreateUserParams) (api.CreateUserRes, error)

func (Handler) DeleteFlowDefinition 

func (h Handler) DeleteFlowDefinition(ctx context.Context, params api.DeleteFlowDefinitionParams) (api.DeleteFlowDefinitionRes, error)

func (*Handler) DeleteGrant 

func (h *Handler) DeleteGrant(ctx context.Context, params api.DeleteGrantParams) (api.DeleteGrantRes, error)

func (*Handler) DeleteTeam 

func (h *Handler) DeleteTeam(ctx context.Context, params api.DeleteTeamParams) (api.DeleteTeamRes, error)

func (*Handler) DeleteUserByID 

func (h *Handler) DeleteUserByID(ctx context.Context, params api.DeleteUserByIDParams) (api.DeleteUserByIDRes, error)

func (Handler) ExchangeHandoff 

func (h Handler) ExchangeHandoff(ctx context.Context, req *api.ExchangeRequest, params api.ExchangeHandoffParams) (api.ExchangeHandoffRes, error)

func (*Handler) FinishUserPasskeyRegistration 

func (h *Handler) FinishUserPasskeyRegistration(ctx context.Context, req *api.FinishUserPasskeyRegistrationRequest, params api.FinishUserPasskeyRegistrationParams) (api.FinishUserPasskeyRegistrationRes, error)

FinishUserPasskeyRegistration verifies the attestation and persists the new credential; the service consumes the ceremony atomically.

func (Handler) GetAuthAttempt 

func (h Handler) GetAuthAttempt(ctx context.Context, params api.GetAuthAttemptParams) (api.GetAuthAttemptRes, error)

func (*Handler) GetBrandingById 

func (h *Handler) GetBrandingById(ctx context.Context, params api.GetBrandingByIdParams) (api.GetBrandingByIdRes, error)

func (*Handler) GetClaimStatus 

func (h *Handler) GetClaimStatus(ctx context.Context, params api.GetClaimStatusParams) (api.GetClaimStatusRes, error)

func (*Handler) GetClaimWindow 

func (h *Handler) GetClaimWindow(ctx context.Context, params api.GetClaimWindowParams) (api.GetClaimWindowRes, error)

GetClaimWindow answers the claim page's countdown read. Unauthenticated by contract (`security: []`): the page runs it before the developer signs in, and the challenge from the claim URL is the capability. A challenge that does not resolve answers 404 through claimErrorResponse, the same verdict a wrong project id gets, so nothing about project existence leaks.

func (*Handler) GetEnvironmentByName 

func (h *Handler) GetEnvironmentByName(ctx context.Context, params api.GetEnvironmentByNameParams) (api.GetEnvironmentByNameRes, error)

func (*Handler) GetEvent 

func (h *Handler) GetEvent(ctx context.Context, params api.GetEventParams) (api.GetEventRes, error)

func (Handler) GetFlowDefinition 

func (h Handler) GetFlowDefinition(ctx context.Context, params api.GetFlowDefinitionParams) (api.GetFlowDefinitionRes, error)

func (*Handler) GetFlowStep 

func (h *Handler) GetFlowStep(ctx context.Context, params api.GetFlowStepParams) (api.GetFlowStepRes, error)

func (*Handler) GetGrant 

func (h *Handler) GetGrant(ctx context.Context, params api.GetGrantParams) (api.GetGrantRes, error)

func (*Handler) GetHealth 

func (h *Handler) GetHealth(ctx context.Context) (api.GetHealthRes, error)

func (*Handler) GetLive 

func (h *Handler) GetLive(ctx context.Context) (api.GetLiveRes, error)

func (Handler) GetMySession 

func (h Handler) GetMySession(ctx context.Context) (api.GetMySessionRes, error)

func (*Handler) GetMyUser 

func (h *Handler) GetMyUser(ctx context.Context) (api.GetMyUserRes, error)

func (*Handler) GetProject 

func (h *Handler) GetProject(ctx context.Context, params api.GetProjectParams) (api.GetProjectRes, error)

func (*Handler) GetReady 

func (h *Handler) GetReady(ctx context.Context) (api.GetReadyRes, error)

func (*Handler) GetSchemaById 

func (h *Handler) GetSchemaById(ctx context.Context, params api.GetSchemaByIdParams) (api.GetSchemaByIdRes, error)

func (Handler) GetSession 

func (h Handler) GetSession(ctx context.Context, params api.GetSessionParams) (api.GetSessionRes, error)

func (*Handler) GetTeam 

func (h *Handler) GetTeam(ctx context.Context, params api.GetTeamParams) (api.GetTeamRes, error)

func (*Handler) GetUserByID 

func (h *Handler) GetUserByID(ctx context.Context, params api.GetUserByIDParams) (api.GetUserByIDRes, error)

func (*Handler) InitClaim 

func (h *Handler) InitClaim(ctx context.Context, params api.InitClaimParams) (api.InitClaimRes, error)

func (Handler) IssueChallenge 

func (h Handler) IssueChallenge(ctx context.Context, req *api.IssueChallengeRequest, params api.IssueChallengeParams) (api.IssueChallengeRes, error)

func (*Handler) ListBranding 

func (h *Handler) ListBranding(ctx context.Context, params api.ListBrandingParams) (api.ListBrandingRes, error)

func (*Handler) ListEnvironments 

func (h *Handler) ListEnvironments(ctx context.Context, params api.ListEnvironmentsParams) (api.ListEnvironmentsRes, error)

func (*Handler) ListEvents 

func (h *Handler) ListEvents(ctx context.Context, params api.ListEventsParams) (api.ListEventsRes, error)

func (Handler) ListFlowDefinitions 

func (h Handler) ListFlowDefinitions(ctx context.Context, params api.ListFlowDefinitionsParams) (api.ListFlowDefinitionsRes, error)

func (*Handler) ListSchemas 

func (h *Handler) ListSchemas(ctx context.Context, params api.ListSchemasParams) (api.ListSchemasRes, error)

func (*Handler) ListUserPasskeys 

func (h *Handler) ListUserPasskeys(ctx context.Context, params api.ListUserPasskeysParams) (api.ListUserPasskeysRes, error)

func (*Handler) ListUserTeams 

func (h *Handler) ListUserTeams(ctx context.Context, params api.ListUserTeamsParams) (api.ListUserTeamsRes, error)

ListUserTeams serves the user's team roster — the N:N membership list, one page at a time, each entry carrying the team's name so a client renders the page without resolving ids one by one. Lifecycle ownership is a different question and stays on the user itself (ADR 024).

func (*Handler) NewError 

func (h *Handler) NewError(ctx context.Context, err error) *api.ErrorDetailsStatusCode

NewError implements the api.Handler interface and is used by ogen to convert any error returned by an endpoint handler into a well-formed error response. By centralizing this logic here, we can ensure that all errors are handled consistently regardless of where they originate.

func (*Handler) PatchProject 

func (h *Handler) PatchProject(ctx context.Context, req *api.PatchProjectRequest, params api.PatchProjectParams) (api.PatchProjectRes, error)

func (*Handler) QueryGrants 

func (h *Handler) QueryGrants(ctx context.Context, req *api.QueryGrantsRequest, params api.QueryGrantsParams) (api.QueryGrantsRes, error)

func (*Handler) QueryProjects 

func (h *Handler) QueryProjects(ctx context.Context, req *api.QueryProjectsRequest) (api.QueryProjectsRes, error)

QueryProjects has no project parameter: results are restricted to the caller's project. The authz gate rejects an unbound / no-foothold scope, so the ProjectID passed on is always set.

func (Handler) QuerySessions 

func (h Handler) QuerySessions(ctx context.Context, req *api.QuerySessionsRequest, params api.QuerySessionsParams) (api.QuerySessionsRes, error)

func (*Handler) QueryTeams 

func (h *Handler) QueryTeams(ctx context.Context, req *api.QueryTeamsRequest, params api.QueryTeamsParams) (api.QueryTeamsRes, error)

func (*Handler) QueryUsers 

func (h *Handler) QueryUsers(ctx context.Context, req *api.QueryUsersRequest) (api.QueryUsersRes, error)

QueryUsers is the users list (ADR 031). It carries no project parameter: the oauth2 principal (the project secret the CLI's status probe sends) is the only authority for which project's users are served, so the scope check is what keeps a browser-plane preview secret out. Results are newest-first unless the request sorts otherwise.

func (Handler) RevokeMySession 

func (h Handler) RevokeMySession(ctx context.Context) (api.RevokeMySessionRes, error)

func (Handler) RevokeSession 

func (h Handler) RevokeSession(ctx context.Context, params api.RevokeSessionParams) (api.RevokeSessionRes, error)

func (*Handler) SetUserPassword 

func (h *Handler) SetUserPassword(ctx context.Context, req *api.SetUserPasswordRequest, params api.SetUserPasswordParams) (api.SetUserPasswordRes, error)

func (*Handler) SubmitFlowStep 

func (h *Handler) SubmitFlowStep(ctx context.Context, req *api.FlowSubmitRequest, params api.SubmitFlowStepParams) (api.SubmitFlowStepRes, error)

func (Handler) UpdateFlowDefinition 

func (h Handler) UpdateFlowDefinition(ctx context.Context, req *api.FlowDefinitionUpdateRequest, params api.UpdateFlowDefinitionParams) (api.UpdateFlowDefinitionRes, error)

func (*Handler) UpdateTeam 

func (h *Handler) UpdateTeam(ctx context.Context, req *api.UpdateTeamRequest, params api.UpdateTeamParams) (api.UpdateTeamRes, error)

func (Handler) VerifyChallengeProof 

func (h Handler) VerifyChallengeProof(ctx context.Context, req *api.VerifyChallengeRequest, params api.VerifyChallengeProofParams) (api.VerifyChallengeProofRes, error)

func (*Handler) WithPersonalTeamEnsurer 

func (h *Handler) WithPersonalTeamEnsurer(e service.PersonalTeamEnsurer) *Handler

WithPersonalTeamEnsurer wires the session-exchange self-heal for platform personal teams (#527). A chainable setter rather than a constructor parameter so the existing NewHandler call sites (tests included) stay untouched; without it the exchange simply skips the ensure.

type ScopeContext 

type ScopeContext struct {
	ProjectID string
	// Scope carries the token's minted scopes verbatim (domain.Token.Scope):
	// project secrets hold project.write + project.read, preview secrets hold
	// project.read only. The authz gate requires project.write as a ceiling on
	// top of resolver.Check — preview cannot call management APIs at all.
	Scope []string
	// PrincipalType / PrincipalID identify the authz principal for resolver.Check.
	// OAuth2 project secrets are sk_proj with PrincipalID == ProjectID.
	PrincipalType domain.AuthzPrincipalType
	PrincipalID   string
	// TeamID is the token team for sk_team_ principals (resolver ConstraintTeamID).
	TeamID string
	// SecretHash is domain.HashSecret of the presented bearer string: the
	// proof-of-possession seam for the claim flow (ADR 046 §3). The claim
	// service stores it on init and compares it on status; it is set only on
	// those two operations.
	SecretHash string
}

func GetScopeContext 

func GetScopeContext(ctx context.Context) (ScopeContext, bool)

type SecurityHandler 

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

func NewSecurityHandler 

func NewSecurityHandler(
	tokenService service.TokenService,
) *SecurityHandler

func (SecurityHandler) HandleNextgenSession 

func (s SecurityHandler) HandleNextgenSession(ctx context.Context, operationName api.OperationName, t api.NextgenSession) (context.Context, error)

HandleNextgenSession handles the nextgenSession security scheme: the __nextgen_session cookie on the sessions/me and users/me operations. It verifies that the cookie value decrypts to a session token and stashes the parsed token in the context for the handlers.

func (SecurityHandler) HandleOAuth2 

func (s SecurityHandler) HandleOAuth2(ctx context.Context, operationName api.OperationName, t api.OAuth2) (context.Context, error)

Source Files

View all Source files

Directories

Path Synopsis
integration_test
helpers
test_data

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.