auth

Documentation

Index

• Constants
• func CallbackFilePath() (string, error)
• func DeleteClientSecret(clientID string) error
• func HandleCallbackURL(rawURL string) error
• func LoadClientSecret(clientID string) (string, error)
• func MigrateClientSecretFromEnv(clientID, envSecret string) (bool, error)
• func RegisterProtocol(binaryPath string) error
• func RestrictFileAccess(_ string) error
• func SaveClientSecret(clientID, secret string) error
• func WriteCallbackFile(code, state, errMsg string) error
• type OAuthConfig
• type OAuthProvider
  • func NewOAuthProvider(config OAuthConfig) (*OAuthProvider, error)
  • func (p *OAuthProvider) Authorize(ctx context.Context) error
  • func (p *OAuthProvider) Logout() error
  • func (p *OAuthProvider) NeedsAuth() bool
  • func (p *OAuthProvider) Token() (string, error)
• type StaticProvider
  • func NewStaticProvider(token string) *StaticProvider
  • func (p *StaticProvider) Token() (string, error)
• type StoredTokens
• type TokenStore
  • func NewTokenStore() (*TokenStore, error)
  • func (s *TokenStore) Delete() error
  • func (s *TokenStore) Load() (*StoredTokens, error)
  • func (s *TokenStore) MigrateTokensFromFile() (bool, error)
  • func (s *TokenStore) Path() string
  • func (s *TokenStore) Save(tokens *StoredTokens) error
  • func (s *TokenStore) UsingKeyring() bool

Constants

const (
	// ProtocolScheme is the custom URI scheme for OAuth callbacks.
	ProtocolScheme = "wmcp"

	// ProtocolCallbackURL is the redirect URI to register with Webex.
	ProtocolCallbackURL = ProtocolScheme + "://oauth-callback"
)

const (

	// DefaultScopes covers the APIs this plugin uses.
	//
	// spark:all is required (not just the granular spark:messages_* /
	// spark:rooms_* scopes) because the real-time WebSocket listener
	// registers a Mercury device with WDM (wdm-a.wbx2.com), and that
	// endpoint rejects granular-scoped tokens with HTTP 403. spark:all is
	// the only public OAuth scope that grants it — matching what a PAT
	// carries. The meeting:* scopes are a separate family that spark:all
	// does NOT cover, so they're listed explicitly.
	// Override with the WEBEX_SCOPES env var.
	DefaultScopes = "spark:all meeting:schedules_read meeting:transcripts_read"
)

Functions

func CallbackFilePath

func CallbackFilePath() (string, error)

CallbackFilePath returns the path where the callback handler writes the auth code.

func DeleteClientSecret

func DeleteClientSecret(clientID string) error

DeleteClientSecret removes a stored client secret.

func HandleCallbackURL

func HandleCallbackURL(rawURL string) error

HandleCallbackURL parses a wmcp:// URL from the OS and writes the callback file. Called by `webex-mcp --oauth-callback <url>`.

func LoadClientSecret

func LoadClientSecret(clientID string) (string, error)

LoadClientSecret returns the OAuth client secret for the given clientID from the OS keychain, falling back to a 0600 file when the keychain is unavailable. Returns os.ErrNotExist if no secret is stored.

func MigrateClientSecretFromEnv

func MigrateClientSecretFromEnv(clientID, envSecret string) (bool, error)

MigrateClientSecretFromEnv writes the client secret from the environment into the keychain when one isn't already stored for this clientID. Returns true when a new entry was written. The env var is left in place; removing it from the user's shell or .mcp.json is the user's job.

func RegisterProtocol

func RegisterProtocol(binaryPath string) error

RegisterProtocol registers the wmcp:// custom URI scheme with the OS so that OAuth callbacks open the webex-mcp binary.

func RestrictFileAccess

func RestrictFileAccess(_ string) error

RestrictFileAccess is a no-op on Unix — os.WriteFile with 0600 mode correctly restricts permissions via POSIX file mode bits.

func SaveClientSecret

func SaveClientSecret(clientID, secret string) error

SaveClientSecret writes the OAuth client secret to the OS keychain, falling back to a 0600 file with restricted ACL when the keychain is unavailable.

func WriteCallbackFile

func WriteCallbackFile(code, state, errMsg string) error

WriteCallbackFile is called by the --oauth-callback handler to deliver the authorization code to the waiting Authorize() call via the filesystem.

Types

type OAuthConfig

type OAuthConfig struct {
	ClientID     string
	ClientSecret string
	RedirectURI  string // Optional; defaults to wmcp://oauth-callback.
	Scopes       string // Optional; defaults to DefaultScopes.
}

OAuthConfig holds the OAuth integration credentials.

type OAuthProvider

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

OAuthProvider manages OAuth tokens with automatic refresh.

func NewOAuthProvider

func NewOAuthProvider(config OAuthConfig) (*OAuthProvider, error)

NewOAuthProvider creates a provider that handles the full OAuth lifecycle. It loads any previously stored tokens automatically.

func (*OAuthProvider) Authorize

func (p *OAuthProvider) Authorize(ctx context.Context) error

Authorize runs the interactive OAuth authorization code flow with PKCE. It opens the browser, then polls for the callback file written by the wmcp:// protocol handler. No HTTP listener is used.

func (*OAuthProvider) Logout

func (p *OAuthProvider) Logout() error

Logout removes stored tokens.

func (*OAuthProvider) NeedsAuth

func (p *OAuthProvider) NeedsAuth() bool

NeedsAuth returns true if the user must go through the browser OAuth flow.

func (*OAuthProvider) Token

func (p *OAuthProvider) Token() (string, error)

Token returns a valid access token, refreshing if needed.

type StaticProvider

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

StaticProvider wraps a fixed Personal Access Token.

func NewStaticProvider

func NewStaticProvider(token string) *StaticProvider

NewStaticProvider creates a provider that always returns the same token.

func (*StaticProvider) Token

func (p *StaticProvider) Token() (string, error)

Token returns the static access token.

type StoredTokens

type StoredTokens struct {
	AccessToken           string    `json:"access_token"`
	RefreshToken          string    `json:"refresh_token"`
	AccessTokenExpiresAt  time.Time `json:"access_token_expires_at"`
	RefreshTokenExpiresAt time.Time `json:"refresh_token_expires_at"`
}

StoredTokens holds persisted OAuth tokens.

type TokenStore

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

TokenStore handles persistent OAuth token storage. It prefers the OS keychain (Windows Credential Manager, macOS Keychain, Linux Secret Service) and falls back to a 0600 file when no keychain backend is available — common on headless Linux, WSL, and minimal containers.

func NewTokenStore

func NewTokenStore() (*TokenStore, error)

NewTokenStore creates a store backed by the OS keychain when available, otherwise a file at the user's config directory.

func (*TokenStore) Delete

func (s *TokenStore) Delete() error

Delete removes stored tokens.

func (*TokenStore) Load

func (s *TokenStore) Load() (*StoredTokens, error)

Load reads stored tokens from the keychain or fallback file.

func (*TokenStore) MigrateTokensFromFile

func (s *TokenStore) MigrateTokensFromFile() (bool, error)

MigrateTokensFromFile imports a pre-v0.8.0 tokens.json file into the keychain and removes the on-disk copy. Returns true if a migration happened. Safe to call when no legacy file exists; it returns (false, nil) in that case.

On systems without a keychain backend (Linux without Secret Service), migration is a no-op: the file already lives at the same path the fallback uses, so it's already correctly placed.

func (*TokenStore) Path

func (s *TokenStore) Path() string

Path returns the file fallback path. Empty result indicates the store is keychain-backed and has no on-disk path.

func (*TokenStore) Save

func (s *TokenStore) Save(tokens *StoredTokens) error

Save writes tokens to the keychain or fallback file with restricted permissions. On Windows the file fallback path is rarely used (Credential Manager is always available), but if it is, NTFS ACLs are explicitly set via icacls because Go's 0600 mode has no effect on NTFS.

func (*TokenStore) UsingKeyring

func (s *TokenStore) UsingKeyring() bool

UsingKeyring reports whether the store reads/writes from the OS keychain.