Help us shape the future of Go! Take the 2026 Go Developer Survey

oauthlogin

package
v0.0.49 Latest Latest
Warning

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

Go to latest
Published: Oct 20, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package oauthlogin provides an opt-in, host-side OAuth loopback login runtime.

Index

Constants

View Source
const (

	// ExactRedirectURL is the fixed callback URI used by remote mecatui login.
	// It is deliberately IPv4-literal and must not be changed to localhost or
	// a wildcard address.
	ExactRedirectURL = "http://" + exactRedirectAddress + fixedCallbackPath

	// ToolHiveCompatibleRedirectURL is the fixed callback URI used by native
	// LLM login so an existing ToolHive-compatible client registration works.
	ToolHiveCompatibleRedirectURL = "http://localhost:8666/callback"
)

Variables

View Source
var (
	// ErrAuthorizationFailed reports a redacted failure of the authorization interaction.
	ErrAuthorizationFailed = errors.New("OAuth authorization failed")
	// ErrCallbackAttempts reports exhaustion of the callback request budget.
	ErrCallbackAttempts = errors.New("OAuth callback request limit exceeded")
)
View Source
var ErrBrowserLaunch = errors.New("could not open browser")

ErrBrowserLaunch indicates that the fixed host browser launcher could not start.

Functions

This section is empty.

Types

type AuthorizationErrorResponse added in v0.0.22

type AuthorizationErrorResponse struct {
	Code        string
	Description string
}

AuthorizationErrorResponse carries the provider's OAuth error response from the callback. Both fields are surfaced: an authorization that fails at the provider is otherwise undiagnosable without reproducing the request by hand, and the operator owns the authorization server being quoted. They are sanitized, not withheld -- RFC 6749 section 4.1.2.1 restricts these values to a printable subset, so anything outside it is dropped rather than echoed, and each field is clamped. That defeats log injection and unbounded output without hiding the one thing the operator needs.

func (*AuthorizationErrorResponse) Error added in v0.0.22

func (*AuthorizationErrorResponse) Is added in v0.0.22

Is reports the sentinel this error stands in for.

func (*AuthorizationErrorResponse) Sanitized added in v0.0.22

Sanitized returns a bounded copy safe for crossing diagnostic boundaries.

type AuthorizeFunc

type AuthorizeFunc func(ctx context.Context, redirectURL string, present func(context.Context, string) (Result, error)) error

AuthorizeFunc performs the controller-owned OAuth operation. It may call present once.

type BrowserLauncher

type BrowserLauncher interface {
	Open(context.Context, string) error
}

BrowserLauncher opens an authorization URL according to host policy.

type CallbackBindError added in v0.0.22

type CallbackBindError struct{ Reason CallbackBindReason }

CallbackBindError reports a callback listener bind failure without retaining the operating-system error, address, or other nested network data.

func (*CallbackBindError) Error added in v0.0.22

func (e *CallbackBindError) Error() string

func (*CallbackBindError) Is added in v0.0.22

func (*CallbackBindError) Is(target error) bool

Is keeps callback bind failures in the authorization-failure category.

type CallbackBindReason added in v0.0.22

type CallbackBindReason uint8

CallbackBindReason is the closed, safe reason a callback listener could not bind.

const (
	// CallbackBindUnavailable reports a bind failure with no safely actionable detail.
	CallbackBindUnavailable CallbackBindReason = iota
	// CallbackBindAddressInUse reports that another process owns the callback address.
	CallbackBindAddressInUse
)

type CallbackRejectedError added in v0.0.22

type CallbackRejectedError struct{ Reason string }

CallbackRejectedError names the rule that rejected an authenticated callback. It satisfies errors.Is(err, ErrAuthorizationFailed) so existing callers that test for that sentinel keep working.

func (*CallbackRejectedError) Error added in v0.0.22

func (e *CallbackRejectedError) Error() string

func (*CallbackRejectedError) Is added in v0.0.22

func (*CallbackRejectedError) Is(target error) bool

Is reports the sentinel this error stands in for.

func (*CallbackRejectedError) Sanitized added in v0.0.22

Sanitized returns a copy containing only a callback validator's closed reason.

type Options

type Options struct {
	NoBrowser bool
	URLWriter io.Writer
	Launcher  BrowserLauncher

	// RedirectURL enables an explicitly configured callback with a FIXED PORT as
	// well as a fixed path. Only the package's fixed redirect constants
	// (ExactRedirectURL, ToolHiveCompatibleRedirectURL) are accepted. Use this only
	// for a target that requires an exact redirect_uri string match (a
	// general-purpose OIDC or ToolHive-compatible target with no obligation to
	// implement RFC 8252 loopback dynamic-port matching) — it reintroduces local
	// port-squatting exposure that PinCallbackPath does not (see its doc comment).
	// Mutually exclusive with PinCallbackPath. Empty preserves the random-path,
	// ephemeral-port default.
	RedirectURL string

	// PinCallbackPath fixes the callback's PATH to the same well-known value
	// ExactRedirectURL uses, while still binding an EPHEMERAL port. Use this for a
	// target whose authorization server implements RFC 8252 §7.3 loopback dynamic-
	// port matching — the AS accepts any port for a registered loopback redirect_uri
	// as long as the path matches — which lets a client register one fixed
	// redirect_uri while every login still gets its own unpredictable port,
	// preserving the squatting resistance a fixed port gives up. Mutually exclusive
	// with RedirectURL: New rejects setting both rather than silently picking one.
	// A per-call explicit callback path (AuthorizeWithCallbackPath, used for DCR's
	// own registration-bound path) always takes priority over this option, since
	// that path — not this well-known one — is what a DCR client actually
	// registered; see resolveCallbackMode's case order.
	PinCallbackPath bool
}

Options configures a Runtime.

type Result

type Result struct {
	Code  string
	State string
	Iss   string
}

Result is the validated loopback authorization response.

type Runtime

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

Runtime serializes complete loopback authorization interactions.

func New

func New(opts Options) (*Runtime, error)

New constructs an opt-in loopback runtime.

func (*Runtime) Authorize

func (r *Runtime) Authorize(ctx context.Context, expectedIssuer string, authorize AuthorizeFunc) error

Authorize runs one loopback authorization interaction. Calls on the same Runtime are serialized.

func (*Runtime) AuthorizeWithCallbackPath added in v0.0.37

func (r *Runtime) AuthorizeWithCallbackPath(ctx context.Context, expectedIssuer, callbackPath string, authorize AuthorizeFunc) error

AuthorizeWithCallbackPath runs one loopback authorization interaction using a registration-bound random callback path and a fresh ephemeral IPv4 port.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL