Documentation
¶
Overview ¶
Package obo provides the proxy-runtime middleware factory hook for the on-behalf-of (OBO) external auth type. The default factory produces a stub middleware that responds 503 to every request. An out-of-tree build replaces the factory by calling RegisterFactory once during init().
Index ¶
Constants ¶
const MiddlewareType = "obo"
MiddlewareType is the type identifier used in MiddlewareConfig.Type for OBO middleware. Matches the ExternalAuthType constant value "obo".
Variables ¶
var ErrEnterpriseRequired = errors.New(
"on-behalf-of (OBO) external auth type requires an enterprise build")
ErrEnterpriseRequired is returned by every default OBO dispatch point — the controllerutil handler hook, the vMCP converter stub, and the middleware stub — when no out-of-tree handler/factory has been registered. Callers must use errors.Is to compare; the error wraps cleanly through fmt.Errorf("...: %w", ...).
Lives in pkg/auth/obo (a leaf package) so that callers in cmd/thv-operator/... and pkg/vmcp/... can share the same sentinel without either layer importing the other. To register an out-of-tree handler, see controllerutil.RegisterOBOHandler (for the operator dispatch points) and obo.RegisterFactory (for the proxy middleware factory).
Functions ¶
func CreateMiddleware ¶
func CreateMiddleware(config *types.MiddlewareConfig, runner types.MiddlewareRunner) error
CreateMiddleware is the package-level middleware factory. It is a stable indirection over currentFactory: each call dispatches to whatever factory is registered at call time, so out-of-tree builds replacing the factory via RegisterFactory take effect on subsequent calls even if a caller has already captured CreateMiddleware itself (e.g. pkg/runner builds its factory map once and reuses it across runner instances). The default produces a 503 stub.
Declared as a function (matching sibling middleware packages such as awssts, upstreamswap, and oauthproto/tokenexchange) so RegisterFactory is the only mutation path — there is no second escape hatch via direct assignment to CreateMiddleware.
func DefaultFactory ¶
func DefaultFactory(config *types.MiddlewareConfig, runner types.MiddlewareRunner) error
DefaultFactory adds a stub middleware whose handler responds 503 to every request. Exposed primarily so external test code (e.g. pkg/runner) can pass it to RegisterFactory in a t.Cleanup to restore the package's default behavior after a test mutates currentFactory.
func RegisterFactory ¶
func RegisterFactory(f types.MiddlewareFactory)
RegisterFactory replaces the underlying middleware factory. Calling it more than once is allowed and last-write-wins, matching the existing pkg/config.RegisterProviderFactory precedent. Panics if f is nil — a nil factory would dispatch into a nil function on the next CreateMiddleware call, far from the registration site; surface the problem at init() time instead.
Types ¶
type ValidationError ¶ added in v0.28.2
type ValidationError struct {
Message string
}
ValidationError is the typed error an OBO handler returns when its input is genuinely malformed and the user must fix the spec for the failure to clear. It is the contract for the "permanent, user-fix" bucket in the OBOHandler error triage:
- errors.Is(err, ErrEnterpriseRequired) → not licensed; permanent until an out-of-tree handler is registered.
- errors.As(err, &*ValidationError) → permanent until the user edits the spec; the operator writes condition.Reason=InvalidConfig and does not requeue.
- anything else → treated as transient by the reconciler, which returns the error so controller-runtime requeues with backoff.
Handler authors must use ValidationError for any condition the user can fix by editing the spec (missing field, malformed URL, schema violation) and must return a non-ValidationError for transient I/O failures (Secret not yet available, JWKS unreachable, webhook 5xx) so the reconciler retries instead of locking the resource into a permanent InvalidConfig state.
The Message field is written verbatim into condition.Message — handler authors are responsible for ensuring it is safe to expose (no Secret names, no internal addressing, no credential fragments).
func (*ValidationError) Error ¶ added in v0.28.2
func (e *ValidationError) Error() string
Error returns the user-facing message verbatim. The OBO branch in the MCPExternalAuthConfig reconciler writes this string into the Valid condition's Message field.
Source Files