authbroker

Documentation

Overview

Package authbroker bridges Poe's turn-based chat into fir's _meta.auth.interactive two-call OAuth protocol.

Each Poe conversation can have at most one in-flight login. The first login command (e.g. "!login anthropic") calls fir's authenticate to produce a URL; the next user turn from the same conversation submits the pasted redirect URL. The broker holds no goroutines — the actual blocking on the user input happens inside fir, parked across turns. The relay only remembers which conversation has a pending login for which method.

Commands accept the sigils "/", "!", and "." but user-facing prose suggests "!" (DisplaySigil): Poe's chat client intercepts "/"-prefixed messages as native slash commands and rejects unknown ones before they reach the bot, so "/login" is unreliable; "!"/"." pass straight through.

Index

• Constants
• func IsLoginCommand(text string) bool
• type Authenticator
• type Broker
  • func New(a Authenticator) *Broker
  • func (b *Broker) Handle(ctx context.Context, convID, text string) (*Outcome, error)
  • func (b *Broker) HasPending(convID string) bool
  • func (b *Broker) OfferLogin() string
• type Outcome

Constants

const DisplaySigil = "!"

DisplaySigil is the command prefix shown in user-facing messages. It is deliberately not "/" so the suggested commands survive Poe's client-side slash-command interceptor.

Functions

func IsLoginCommand

func IsLoginCommand(text string) bool

IsLoginCommand reports whether text is a login/logins/cancel-login command under any accepted sigil (/, !, .). Trims leading whitespace so users can paste the command after a thought.

Types

type Authenticator

type Authenticator interface {
	AuthMethods() []client.AuthMethod
	Authenticate(ctx context.Context, methodID, id, redirect string, cancel bool) (client.AuthResult, error)
}

Authenticator is the agent-side surface the broker depends on. The full *client.AgentProc satisfies it.

type Broker

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

Broker tracks per-conversation pending logins.

func New

func New(a Authenticator) *Broker

New constructs a Broker.

func (*Broker) Handle

func (b *Broker) Handle(ctx context.Context, convID, text string) (*Outcome, error)

Handle dispatches one user turn. Behaviour:

1. If the conversation has a pending login, treat any non-command text as the pasted redirect URL.
2. Otherwise interpret /login [provider], /logins, /cancel-login.

Returns (nil, nil) if the turn is not auth-related and should be forwarded to the normal prompt path.

func (*Broker) HasPending

func (b *Broker) HasPending(convID string) bool

HasPending reports whether the conversation is waiting for a pasted redirect URL.

func (*Broker) OfferLogin

func (b *Broker) OfferLogin() string

OfferLogin renders the onboarding message shown when the agent reports that no usable provider is connected (an "Authentication required" prompt error). It lists the loginable providers using the Poe-safe DisplaySigil. Safe for concurrent use. Returned text is empty-safe: it always yields actionable guidance, even with no OAuth methods.

type Outcome

type Outcome struct {
	// Text is a plain message to stream as a Poe `text` event.
	Text string
	// URL, if non-empty, is the auth URL to surface to the user. Text
	// may also be set with prose preceding/following the URL.
	URL string
	// Instructions accompany URL.
	Instructions string
}

Outcome is what the HTTP handler should render to the user. Exactly one of Text / URL / Error is set; Done is always implied (the auth turn never streams further chunks).