api

package
v1.0.0-alpha.25 Latest Latest
Warning

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

 Go to latest Published: Oct 8, 2026 License: AGPL-3.0 Imports: 34 Imported by: 0

Documentation

Index

Constants

View Source 
const CSRFHeader = "X-Zitadel-CSRF"

CSRFHeader carries the session-bound CSRF token on cookie-authenticated management writes (ADR 053 §5).

View Source 
const IDPCallbackPath = "/__nextgen/idp/callback"

IDPCallbackPath is the route the provider sends the browser back to, under the request origin. Exported for the mux, which mounts IDPCallbackHandler on it ahead of the API catch-all: the instance receives this path when it is the browser origin itself (hosted login).

View Source 
const IDPCallbackUpstreamPath = "/idp/callback"

IDPCallbackUpstreamPath is the same route as it arrives through a scaffolded app's SDK middleware, which strips its proxyPath prefix (`/__nextgen` by default) before forwarding. The mux mounts the same handler on both.

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 CSRFRequestRecorded 

func CSRFRequestRecorded(ctx context.Context) bool

CSRFRequestRecorded reports whether WithCSRFRequest ran for the request ctx belongs to. The server's wiring test uses it to pin that the middleware sits in front of the API, since checkSessionCSRF refuses every cookie-authenticated request without it.

func CSRFToken 

func CSRFToken(sessionCookie string) string

CSRFToken derives the CSRF token for a session cookie value: an HMAC-SHA256 keyed by the cookie over a fixed label. Only a holder of the HttpOnly cookie can compute or learn it — from GET /sessions/me/csrf, which a cross-site page cannot read — so it binds the header to the session without server-side state or keys.

func OgenErrorHandler 

func OgenErrorHandler(ctx 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 WithCSRFRequest 

func WithCSRFRequest(next http.Handler) http.Handler

WithCSRFRequest records the request's method, cross-origin verdict and CSRF header for HandleNextgenSession. It rejects nothing itself: whether a check applies depends on the operation and on the credential that authenticated it, which only the security handler knows.

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). A chain of proxies may send either forwarded header as a comma-separated list; its first entry is the one the client's request arrived with.

func WithScopeContext 

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

func WithSessionStateNoStore 

func WithSessionStateNoStore(next http.Handler) http.Handler

WithSessionStateNoStore prevents responses that carry session state or a credential from being stored: GET /sessions/me and GET /sessions/me/csrf, and the flow start, step render and submit, which set the flow cookie and can return the single-use handoff token. It wraps the generated server so the header is also present on security and decoding errors emitted before the operation handler runs. TestWithSessionStateNoStoreCoversTheSpec keeps the GET paths in step with the OpenAPI source.

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,
	releaseService service.ReleaseService,
	idpConnectionService service.IDPConnectionService,
	deploymentService *service.DeploymentService,
	eventService *service.EventService,
	tokenService service.TokenService,
	keyService service.KeyService,
	claimService service.ClaimService,
	grantService *service.GrantService,
	variableService service.VariableService,
	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) CreateDeployment 

func (h *Handler) CreateDeployment(ctx context.Context, req *api.CreateDeploymentRequest, params api.CreateDeploymentParams) (api.CreateDeploymentRes, 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) CreateIdp 

func (h *Handler) CreateIdp(ctx context.Context, req *api.CreateIdpRequest, params api.CreateIdpParams) (api.CreateIdpRes, error)

func (*Handler) CreateProject 

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

func (*Handler) CreateRelease 

func (h *Handler) CreateRelease(ctx context.Context, req *api.CreateReleaseRequest, params api.CreateReleaseParams) (api.CreateReleaseRes, 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) 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) DeleteVariable 

func (h *Handler) DeleteVariable(ctx context.Context, params api.DeleteVariableParams) (api.DeleteVariableRes, 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) GetDeploymentById 

func (h *Handler) GetDeploymentById(ctx context.Context, params api.GetDeploymentByIdParams) (api.GetDeploymentByIdRes, error)

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) GetIdpById 

func (h *Handler) GetIdpById(ctx context.Context, params api.GetIdpByIdParams) (api.GetIdpByIdRes, error)

func (*Handler) GetIdpRevisionById 

func (h *Handler) GetIdpRevisionById(ctx context.Context, params api.GetIdpRevisionByIdParams) (api.GetIdpRevisionByIdRes, 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) GetMySessionCsrfToken 

func (h Handler) GetMySessionCsrfToken(ctx context.Context) (api.GetMySessionCsrfTokenRes, error)

GetMySessionCsrfToken hands the cookie's session its CSRF token (ADR 053 §5). The session is read and checked the way GetMySession does, so a revoked or superseded cookie gets no token.

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) GetReleaseById 

func (h *Handler) GetReleaseById(ctx context.Context, params api.GetReleaseByIdParams) (api.GetReleaseByIdRes, 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) GetVariable 

func (h *Handler) GetVariable(ctx context.Context, params api.GetVariableParams) (api.GetVariableRes, error)

func (*Handler) GetVariables 

func (h *Handler) GetVariables(ctx context.Context, params api.GetVariablesParams) (api.GetVariablesRes, 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) ListDeployments 

func (h *Handler) ListDeployments(ctx context.Context, params api.ListDeploymentsParams) (api.ListDeploymentsRes, 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) ListIdpRevisions 

func (h *Handler) ListIdpRevisions(ctx context.Context, params api.ListIdpRevisionsParams) (api.ListIdpRevisionsRes, error)

func (*Handler) ListMyProjects 

func (h *Handler) ListMyProjects(ctx context.Context, params api.ListMyProjectsParams) (api.ListMyProjectsRes, error)

ListMyProjects answers "which projects can the person behind this session act on". There is no requireProjectAccess here on purpose: the query is itself the authorization, so a caller with no grants gets an empty page rather than a 403.

func (*Handler) ListReleases 

func (h *Handler) ListReleases(ctx context.Context, params api.ListReleasesParams) (api.ListReleasesRes, 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) PatchMyUser 

func (h *Handler) PatchMyUser(ctx context.Context, req *api.PatchMyUserRequest) (api.PatchMyUserRes, error)

func (*Handler) PatchProject 

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

func (*Handler) PatchUserByID 

func (h *Handler) PatchUserByID(ctx context.Context, req *api.PatchUserRequest, params api.PatchUserByIDParams) (api.PatchUserByIDRes, error)

func (*Handler) QueryGrants 

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

func (*Handler) QueryIdps 

func (h *Handler) QueryIdps(ctx context.Context, req *api.QueryIdpsRequest, params api.QueryIdpsParams) (api.QueryIdpsRes, 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, params api.QueryUsersParams) (api.QueryUsersRes, error)

QueryUsers is the users list (ADR 031, #1300 §2), defaulting to the credential's own project. 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) UpdateTeam 

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

func (*Handler) UpdateVariables 

func (h *Handler) UpdateVariables(ctx context.Context, req api.UpdateVariablesRequest, params api.UpdateVariablesParams) (api.UpdateVariablesRes, 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 IDPCallbackHandler 

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

IDPCallbackHandler answers the provider's redirect on IDPCallbackPath. It is a plain net/http handler, not an API operation: the request shape is RFC 6749's, the browser arriving here carries no API credential, and the response is a redirect or an error page, never JSON.

func NewIDPCallbackHandler 

func NewIDPCallbackHandler(callback ssoCallbackProcessor) *IDPCallbackHandler

func (*IDPCallbackHandler) ServeHTTP 

func (h *IDPCallbackHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type ScopeContext 

type ScopeContext struct {
	// ProjectID is the credential's home project. For project secrets it equals
	// the managed project; for a Console session it is the session user's
	// project and may differ from the request target (ADR 053).
	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. Session tokens mint an empty Scope.
	Scope []string
	// PrincipalType / PrincipalID identify the authz principal for resolver.Check.
	// OAuth2 project secrets are sk_proj with PrincipalID == ProjectID.
	// User-bound sessions are user with PrincipalID == token.UserID.
	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. It verifies the cookie decrypts to a session token and stashes it for handlers. User-bound sessions mint ScopeContext so management ops can authorize the human, unless oauth2 already minted one (dual-scheme OR). Anonymous sessions skip the grant/user-query ops so a leftover building cookie cannot 401 a valid Bearer.

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.