client

package
v4.0.0-alpha.13 Latest Latest
Warning

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

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

README

OpenAPI Client Boundary

This package is the supported production boundary around selected generated OpenAPI clients. The generated packages remain the source for request and response DTOs, while this package keeps authentication and supported operation selection explicit.

Supported Surface

Management API:

  • NewManagementClient
  • ManagementClient.GetOpenAPIYAML
  • ManagementClient.GetOpenAPIJSON
  • ManagementClient.ListBruteForceEntries
  • ManagementClient.ListFilteredBruteForceEntries
  • ManagementClient.FlushBruteForceRule
  • ManagementClient.EnqueueBruteForceRuleFlush
  • ManagementClient.FlushUserCache
  • ManagementClient.EnqueueUserCacheFlush
  • ManagementClient.GetAsyncJobStatus
  • ManagementClient.ListOIDCSessions
  • ManagementClient.DeleteOIDCSessions
  • ManagementClient.DeleteOIDCSession
  • BearerToken
  • BasicCredentials

Policy API:

  • NewPolicyClient
  • PolicyClient.Evaluate
  • PolicyBearerToken
  • PolicyBasicCredentials

IdP public discovery API:

  • NewIDPDiscoveryClient
  • IDPDiscoveryClient.GetPublicOpenAPIJSON
  • IDPDiscoveryClient.GetPublicOpenAPIYAML
  • IDPDiscoveryClient.GetOIDCDiscovery
  • IDPDiscoveryClient.GetOIDCJWKS
  • IDPDiscoveryClient.GetSAMLMetadata

The management client boundary requires backchannel authentication. Use BearerToken for Authorization: Bearer ... or BasicCredentials for Authorization: Basic .... The request and response values stay generated types from server/openapi/generated/management.

The Policy client is a separate boundary. Its PolicyAuth type is deliberately not assignable to BackchannelAuth; Policy Bearer tokens and Policy-Basic credentials are accepted only by /api/v1/policy/decisions and must never be used to imply management/backchannel access.

Complete curl examples, bounded-runtime guidance, correlation fields, and failure handling are in the Policy Decision Service operations guide.

Exact Resource Authentication

BearerToken is for the management/backchannel resource and requires an access token whose exact single audience is nauthilus:backchannel plus the issuer-owned non-empty client_id emitted for service tokens. A browser access token cannot qualify by using a colliding client audience. PolicyBearerToken is for the Policy resource and requires all of the following:

  • the normalized audience set is exactly {nauthilus:policy};
  • nauthilus:policy_evaluate is present;
  • nauthilus:policy_diagnostics is also present when sanitized diagnostics are explicitly requested; and
  • the token contains one issuer-validated, issuer-owned client_id that matches an admitted Policy client profile.

Policy authentication never substitutes sub, azp, or iss for a missing or ambiguous client_id. Policy endpoints reject backchannel tokens, and management/backchannel endpoints reject Policy tokens. The constructors do not rewrite scopes or infer an audience; they preserve the caller's explicit token choice.

For Nauthilus-issued client-credentials tokens, scope families are classified before persistence. A request containing one or both Policy-family scopes (nauthilus:policy_evaluate, nauthilus:policy_diagnostics) and no backchannel scope receives aud=nauthilus:policy. A request with no Policy scope, including an empty request or one containing only existing non-Policy service scopes, receives aud=nauthilus:backchannel. Mixing either Policy scope with a backchannel scope fails with invalid_scope and writes no token, session, or flow state. If client filtering would remove or replace an explicitly requested resource family, the request also fails with invalid_scope before issuance. A client that calls both resources must obtain, cache, and rotate two independent tokens. External issuers must preserve the same exact resource separation.

PolicyBasicCredentials is also distinct from management Basic credentials. Policy-Basic has no OAuth scope and receives authority only from its exact enabled Policy client profile over a protected transport. The supported client boundary reaches the active top-level policy generation used by the gRPC adapter and the internal authentication applications; there is no secondary Policy catalog or authentication fallback.

Document-style downloads such as OpenAPI YAML and SAML metadata intentionally return raw *http.Response values from the generated client. JSON management and discovery workflows return generated response wrappers.

Intentional Exclusions

The following surfaces remain outside this supported generated-client boundary:

  • CBOR authentication
  • Header authentication
  • NGINX auth_http authentication
  • OIDC token exchange
  • Browser login and MFA flows
  • SAML SSO/SLO protocol flows
  • WebAuthn

Those flows require protocol-realistic clients and tests. They must not be replaced by generated clients unless the contract tooling can model the protocol behavior without weakening coverage.

Regeneration And Validation

Generated code is committed and regenerated only through the central server workflow:

make generate-openapi-bindings

Check drift with:

make generate-openapi-bindings-check

Run focused client checks with:

GOEXPERIMENT=runtimesecret GOCACHE=/tmp/nauthilus-go-cache go test ./server/openapi/client ./server/openapi/generated/management ./server/openapi/generated/idp

The full server gate is:

GOEXPERIMENT=runtimesecret GOCACHE=/tmp/nauthilus-go-cache make guardrails

Documentation

Overview

Package client exposes the supported production boundary around selected generated OpenAPI clients.

Index

Constants

This section is empty.

Variables

View Source 
var ErrInvalidBackchannelAuth = errors.New("invalid backchannel auth")

ErrInvalidBackchannelAuth reports an incomplete generated management client authentication configuration.

View Source 
var ErrInvalidPolicyAuth = errors.New("invalid policy auth")

ErrInvalidPolicyAuth reports incomplete dedicated Policy client credentials.

View Source 
var ErrNilClient = errors.New("nil generated client")

ErrNilClient reports a nil generated client dependency.

Functions

This section is empty.

Types

type BackchannelAuth 

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

BackchannelAuth contains the supported authentication material for generated management clients.

func BasicCredentials 

func BasicCredentials(username string, password string) BackchannelAuth

BasicCredentials configures Authorization: Basic authentication for generated management clients.

func BearerToken 

func BearerToken(token string) BackchannelAuth

BearerToken configures Authorization: Bearer authentication for generated management clients.

type IDPDiscoveryClient 

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

IDPDiscoveryClient wraps the supported public discovery subset of the generated IDP OpenAPI client.

func NewIDPDiscoveryClient 

func NewIDPDiscoveryClient(server string, options ...generatedidp.ClientOption) (*IDPDiscoveryClient, error)

NewIDPDiscoveryClient creates the supported generated IDP discovery client.

func NewIDPDiscoveryClientFromGenerated 

func NewIDPDiscoveryClientFromGenerated(generated generatedIDPClient) (*IDPDiscoveryClient, error)

NewIDPDiscoveryClientFromGenerated wraps an existing generated IDP client for dependency injection.

func (*IDPDiscoveryClient) GetOIDCDiscovery 

func (client *IDPDiscoveryClient) GetOIDCDiscovery(
	ctx context.Context,
	requestEditors ...generatedidp.RequestEditorFn,
) (*generatedidp.GetOIDCDiscoveryResponse, error)

GetOIDCDiscovery downloads OIDC discovery metadata through the generated client contract.

func (*IDPDiscoveryClient) GetOIDCJWKS 

func (client *IDPDiscoveryClient) GetOIDCJWKS(
	ctx context.Context,
	requestEditors ...generatedidp.RequestEditorFn,
) (*generatedidp.GetOIDCJWKSResponse, error)

GetOIDCJWKS downloads the OIDC JWKS through the generated client contract.

func (*IDPDiscoveryClient) GetPublicOpenAPIJSON 

func (client *IDPDiscoveryClient) GetPublicOpenAPIJSON(
	ctx context.Context,
	requestEditors ...generatedidp.RequestEditorFn,
) (*generatedidp.GetPublicIdPOpenAPIJSONResponse, error)

GetPublicOpenAPIJSON downloads the public IDP OpenAPI JSON document through the generated client contract.

func (*IDPDiscoveryClient) GetPublicOpenAPIYAML 

func (client *IDPDiscoveryClient) GetPublicOpenAPIYAML(
	ctx context.Context,
	requestEditors ...generatedidp.RequestEditorFn,
) (*http.Response, error)

GetPublicOpenAPIYAML downloads the public IDP OpenAPI YAML document as a raw generated client response.

func (*IDPDiscoveryClient) GetSAMLMetadata 

func (client *IDPDiscoveryClient) GetSAMLMetadata(
	ctx context.Context,
	requestEditors ...generatedidp.RequestEditorFn,
) (*http.Response, error)

GetSAMLMetadata downloads SAML metadata as a raw generated client response.

type ManagementClient 

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

ManagementClient wraps the supported subset of the generated management OpenAPI client.

func NewManagementClient 

func NewManagementClient(
	server string,
	auth BackchannelAuth,
	options ...management.ClientOption,
) (*ManagementClient, error)

NewManagementClient creates the supported generated management client with mandatory backchannel authentication.

func NewManagementClientFromGenerated 

func NewManagementClientFromGenerated(generated generatedManagementClient) (*ManagementClient, error)

NewManagementClientFromGenerated wraps an existing generated management client for dependency injection.

func (*ManagementClient) DeleteOIDCSession 

func (client *ManagementClient) DeleteOIDCSession(
	ctx context.Context,
	userID string,
	token string,
	requestEditors ...management.RequestEditorFn,
) (*management.DeleteOIDCSessionResponse, error)

DeleteOIDCSession deletes one OIDC session through the generated management contract.

func (*ManagementClient) DeleteOIDCSessions 

func (client *ManagementClient) DeleteOIDCSessions(
	ctx context.Context,
	userID string,
	requestEditors ...management.RequestEditorFn,
) (*management.DeleteOIDCSessionsResponse, error)

DeleteOIDCSessions deletes all OIDC sessions for one user through the generated management contract.

func (*ManagementClient) EnqueueBruteForceRuleFlush 

func (client *ManagementClient) EnqueueBruteForceRuleFlush(
	ctx context.Context,
	body management.EnqueueBruteForceRuleFlushJSONRequestBody,
	requestEditors ...management.RequestEditorFn,
) (*management.EnqueueBruteForceRuleFlushResponse, error)

EnqueueBruteForceRuleFlush enqueues a brute-force rule flush using generated request and response types.

func (*ManagementClient) EnqueueUserCacheFlush 

func (client *ManagementClient) EnqueueUserCacheFlush(
	ctx context.Context,
	body management.EnqueueUserCacheFlushJSONRequestBody,
	requestEditors ...management.RequestEditorFn,
) (*management.EnqueueUserCacheFlushResponse, error)

EnqueueUserCacheFlush enqueues the supported cache flush operation using the generated request and response types from the management OpenAPI contract.

func (*ManagementClient) FlushBruteForceRule 

func (client *ManagementClient) FlushBruteForceRule(
	ctx context.Context,
	body management.FlushBruteForceRuleJSONRequestBody,
	requestEditors ...management.RequestEditorFn,
) (*management.FlushBruteForceRuleResponse, error)

FlushBruteForceRule flushes one brute-force rule using generated request and response types.

func (*ManagementClient) FlushUserCache 

func (client *ManagementClient) FlushUserCache(
	ctx context.Context,
	body management.FlushUserCacheJSONRequestBody,
	requestEditors ...management.RequestEditorFn,
) (*management.FlushUserCacheResponse, error)

FlushUserCache flushes the user cache synchronously using generated request and response types.

func (*ManagementClient) GetAsyncJobStatus 

func (client *ManagementClient) GetAsyncJobStatus(
	ctx context.Context,
	jobID string,
	requestEditors ...management.RequestEditorFn,
) (*management.GetAsyncJobStatusResponse, error)

GetAsyncJobStatus reads an asynchronous backchannel job status using the generated response types from the management OpenAPI contract.

func (*ManagementClient) GetOpenAPIJSON 

func (client *ManagementClient) GetOpenAPIJSON(
	ctx context.Context,
	requestEditors ...management.RequestEditorFn,
) (*management.GetOpenAPIJSONResponse, error)

GetOpenAPIJSON downloads the management OpenAPI JSON document through the generated client contract.

func (*ManagementClient) GetOpenAPIYAML 

func (client *ManagementClient) GetOpenAPIYAML(
	ctx context.Context,
	requestEditors ...management.RequestEditorFn,
) (*http.Response, error)

GetOpenAPIYAML downloads the management OpenAPI YAML document as a raw generated client response.

func (*ManagementClient) ListBruteForceEntries 

func (client *ManagementClient) ListBruteForceEntries(
	ctx context.Context,
	requestEditors ...management.RequestEditorFn,
) (*management.ListBruteForceEntriesResponse, error)

ListBruteForceEntries lists brute-force entries using generated response types from the management OpenAPI contract.

func (*ManagementClient) ListBruteForceEntriesWithParams 

func (client *ManagementClient) ListBruteForceEntriesWithParams(
	ctx context.Context,
	params *management.ListBruteForceEntriesParams,
	requestEditors ...management.RequestEditorFn,
) (*management.ListBruteForceEntriesResponse, error)

ListBruteForceEntriesWithParams lists brute-force entries with optional paging parameters using generated response types from the management OpenAPI contract.

func (*ManagementClient) ListFilteredBruteForceEntries 

func (client *ManagementClient) ListFilteredBruteForceEntries(
	ctx context.Context,
	body management.ListFilteredBruteForceEntriesJSONRequestBody,
	requestEditors ...management.RequestEditorFn,
) (*management.ListFilteredBruteForceEntriesResponse, error)

ListFilteredBruteForceEntries lists filtered brute-force entries using generated request and response types.

func (*ManagementClient) ListFilteredBruteForceEntriesWithParams 

func (client *ManagementClient) ListFilteredBruteForceEntriesWithParams(
	ctx context.Context,
	params *management.ListFilteredBruteForceEntriesParams,
	body management.ListFilteredBruteForceEntriesJSONRequestBody,
	requestEditors ...management.RequestEditorFn,
) (*management.ListFilteredBruteForceEntriesResponse, error)

ListFilteredBruteForceEntriesWithParams lists filtered brute-force entries with optional paging parameters using generated request and response types.

func (*ManagementClient) ListOIDCSessions 

func (client *ManagementClient) ListOIDCSessions(
	ctx context.Context,
	userID string,
	requestEditors ...management.RequestEditorFn,
) (*management.ListOIDCSessionsResponse, error)

ListOIDCSessions lists OIDC sessions for one user through the generated management contract.

type PolicyAuth 

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

PolicyAuth is private-material Policy authentication and cannot be used as BackchannelAuth.

func PolicyBasicCredentials 

func PolicyBasicCredentials(username string, password string) PolicyAuth

PolicyBasicCredentials configures dedicated Policy-Basic credentials.

func PolicyBearerToken 

func PolicyBearerToken(token string) PolicyAuth

PolicyBearerToken configures a dedicated Policy-resource Bearer credential.

type PolicyClient 

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

PolicyClient wraps the generated client without exposing management authentication types.

func NewPolicyClient 

func NewPolicyClient(server string, auth PolicyAuth, options ...management.ClientOption) (*PolicyClient, error)

NewPolicyClient creates the supported Policy-only generated client.

func NewPolicyClientFromGenerated 

func NewPolicyClientFromGenerated(generated generatedPolicyClient) (*PolicyClient, error)

NewPolicyClientFromGenerated wraps a generated Policy operation seam for dependency injection.

func (*PolicyClient) Evaluate 

func (client *PolicyClient) Evaluate(ctx context.Context, body management.EvaluatePolicyDecisionJSONRequestBody, editors ...management.RequestEditorFn) (*management.EvaluatePolicyDecisionResponse, error)

Evaluate performs exactly one generated Policy decision operation.

type SupportedIDPDiscoveryClient 

type SupportedIDPDiscoveryClient interface {
	GetPublicOpenAPIJSON(context.Context, ...generatedidp.RequestEditorFn) (*generatedidp.GetPublicIdPOpenAPIJSONResponse, error)
	GetPublicOpenAPIYAML(context.Context, ...generatedidp.RequestEditorFn) (*http.Response, error)
	GetOIDCDiscovery(context.Context, ...generatedidp.RequestEditorFn) (*generatedidp.GetOIDCDiscoveryResponse, error)
	GetOIDCJWKS(context.Context, ...generatedidp.RequestEditorFn) (*generatedidp.GetOIDCJWKSResponse, error)
	GetSAMLMetadata(context.Context, ...generatedidp.RequestEditorFn) (*http.Response, error)
}

SupportedIDPDiscoveryClient is the production-supported generated IDP discovery client boundary.

type SupportedManagementClient 

type SupportedManagementClient interface {
	GetOpenAPIYAML(
		context.Context,
		...management.RequestEditorFn,
	) (*http.Response, error)
	GetOpenAPIJSON(
		context.Context,
		...management.RequestEditorFn,
	) (*management.GetOpenAPIJSONResponse, error)
	ListBruteForceEntries(
		context.Context,
		...management.RequestEditorFn,
	) (*management.ListBruteForceEntriesResponse, error)
	ListBruteForceEntriesWithParams(
		context.Context,
		*management.ListBruteForceEntriesParams,
		...management.RequestEditorFn,
	) (*management.ListBruteForceEntriesResponse, error)
	ListFilteredBruteForceEntries(
		context.Context,
		management.ListFilteredBruteForceEntriesJSONRequestBody,
		...management.RequestEditorFn,
	) (*management.ListFilteredBruteForceEntriesResponse, error)
	ListFilteredBruteForceEntriesWithParams(
		context.Context,
		*management.ListFilteredBruteForceEntriesParams,
		management.ListFilteredBruteForceEntriesJSONRequestBody,
		...management.RequestEditorFn,
	) (*management.ListFilteredBruteForceEntriesResponse, error)
	FlushBruteForceRule(
		context.Context,
		management.FlushBruteForceRuleJSONRequestBody,
		...management.RequestEditorFn,
	) (*management.FlushBruteForceRuleResponse, error)
	EnqueueBruteForceRuleFlush(
		context.Context,
		management.EnqueueBruteForceRuleFlushJSONRequestBody,
		...management.RequestEditorFn,
	) (*management.EnqueueBruteForceRuleFlushResponse, error)
	FlushUserCache(
		context.Context,
		management.FlushUserCacheJSONRequestBody,
		...management.RequestEditorFn,
	) (*management.FlushUserCacheResponse, error)
	EnqueueUserCacheFlush(
		context.Context,
		management.EnqueueUserCacheFlushJSONRequestBody,
		...management.RequestEditorFn,
	) (*management.EnqueueUserCacheFlushResponse, error)
	GetAsyncJobStatus(
		context.Context,
		string,
		...management.RequestEditorFn,
	) (*management.GetAsyncJobStatusResponse, error)
	ListOIDCSessions(
		context.Context,
		string,
		...management.RequestEditorFn,
	) (*management.ListOIDCSessionsResponse, error)
	DeleteOIDCSessions(
		context.Context,
		string,
		...management.RequestEditorFn,
	) (*management.DeleteOIDCSessionsResponse, error)
	DeleteOIDCSession(
		context.Context,
		string,
		string,
		...management.RequestEditorFn,
	) (*management.DeleteOIDCSessionResponse, error)
}

SupportedManagementClient is the production-supported generated management client boundary.

type SupportedPolicyClient 

type SupportedPolicyClient interface {
	Evaluate(context.Context, management.EvaluatePolicyDecisionJSONRequestBody, ...management.RequestEditorFn) (*management.EvaluatePolicyDecisionResponse, error)
}

SupportedPolicyClient is the dedicated supported unary Policy API surface.

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.