chore: import upstream snapshot with attribution

internal/oauth/prompter.go

@@ -0,0 +1,65 @@
+package oauth
+
+import (
+	"context"
+	"errors"
+)
+
+// ErrPromptDeclined is returned by a Prompter when the user actively cancels or
+// declines the authorization prompt. It is a deliberate "no", so the flow stops
+// rather than falling back to another channel.
+var ErrPromptDeclined = errors.New("authorization declined by user")
+
+// ErrPromptUnavailable is returned by a Prompter when the prompt could not be
+// delivered at all — for example the client advertised an elicitation capability
+// but the request failed at the transport or protocol level. Unlike
+// ErrPromptDeclined it reflects no user decision, so the flow falls back to a
+// channel that needs no client capability instead of giving up.
+var ErrPromptUnavailable = errors.New("authorization prompt could not be delivered")
+
+// Prompt is the content shown to the user when asking them to authorize.
+type Prompt struct {
+	// Message is a human-readable instruction.
+	Message string
+	// URL is the authorization URL (PKCE) or device verification URI.
+	URL string
+	// UserCode is the device-flow code the user must enter, if any.
+	UserCode string
+}
+
+// Prompter presents authorization prompts to the user out of band from the LLM
+// context — for example via MCP elicitation. Keeping prompts out of the model's
+// context prevents the authorization URL (and any session-bound state) from
+// leaking into tool arguments or transcripts.
+//
+// A nil Prompter is valid and reports no capabilities, which drives the flow to
+// its last-resort channel. Implementations wrap a transport-specific client
+// (e.g. an MCP session); see the ghmcp adapter.
+type Prompter interface {
+	// CanPromptURL reports whether the client can display a URL securely via
+	// URL-mode elicitation.
+	CanPromptURL() bool
+
+	// PromptURL securely presents an authorization URL to the user and blocks
+	// until the user acknowledges, declines, or ctx is done. Returning nil means
+	// the prompt was shown (not that authorization completed); the caller waits
+	// for the OAuth flow itself to finish. It returns ErrPromptDeclined if the
+	// user declines or cancels, or ErrPromptUnavailable if the prompt could not
+	// be delivered.
+	PromptURL(ctx context.Context, p Prompt) error
+
+	// CanPromptForm reports whether the client supports form elicitation, used
+	// to display a device code when URL elicitation is unavailable.
+	CanPromptForm() bool
+
+	// PromptForm presents a textual acknowledgement prompt and blocks until the
+	// user responds. It returns ErrPromptDeclined if the user declines, or
+	// ErrPromptUnavailable if the prompt could not be delivered.
+	PromptForm(ctx context.Context, p Prompt) error
+}
+
+// canPromptURL reports URL support, tolerating a nil Prompter.
+func canPromptURL(p Prompter) bool { return p != nil && p.CanPromptURL() }
+
+// canPromptForm reports form support, tolerating a nil Prompter.
+func canPromptForm(p Prompter) bool { return p != nil && p.CanPromptForm() }