auth

Documentation

Index

• Constants
• func AccessToken(ctx context.Context) (string, error)
• func ConfigDir() (string, error)
• func CredentialsPath() (string, error)
• func DeleteCredentials() error
• func DisconnectRepo(ctx context.Context, repositoryID string) error
• func EffectiveEndpoint() string
• func ForceRefresh(ctx context.Context) (string, error)
• func IsAPIKeyAuth() bool
• func OpenBrowser(url string) error
• func RevokeSession(ctx context.Context, accessToken string) error
• func SaveCredentials(c *Credentials) error
• type AccessRequestResponse
  • func RequestWorkspaceAccess(ctx context.Context, remoteURL, repositoryID string) (*AccessRequestResponse, error)
• type AuthState
  • func GetAuthState() AuthState
• type ConnectRepoResponse
  • func ConnectRepo(ctx context.Context, remoteURL, provider string) (*ConnectRepoResponse, error)
  • func PollConnectRepo(ctx context.Context, state string, interval int) (*ConnectRepoResponse, error)
• type Credentials
  • func LoadCredentials() (*Credentials, error)
  • func (c *Credentials) IsExpired() bool
• type LoginResponse
  • func RequestLogin(ctx context.Context, endpoint, provider string) (*LoginResponse, error)
• type MeResponse
  • func Me(ctx context.Context) (*MeResponse, error)
• type TokenResponse
  • func PollForToken(ctx context.Context, endpoint, state string, interval int) (*TokenResponse, error)

Constants

const DefaultEndpoint = "https://api.semantica.sh"

DefaultEndpoint is used when no override or stored session endpoint exists.

Functions

func AccessToken

func AccessToken(ctx context.Context) (string, error)

AccessToken returns a usable access token. It prefers SEMANTICA_API_KEY, then the stored session, refreshing if needed. It returns ("", nil) when no usable credentials are available.

func ConfigDir

func ConfigDir() (string, error)

ConfigDir returns the semantica config directory.

func CredentialsPath

func CredentialsPath() (string, error)

CredentialsPath returns the full path to the credentials file.

func DeleteCredentials

func DeleteCredentials() error

DeleteCredentials removes credentials from both secure and file storage. Ignores "not found" from either store. Ignores keyring errors when the keyring service is genuinely unavailable (headless/CI) - in that case file deletion alone is sufficient.

func DisconnectRepo

func DisconnectRepo(ctx context.Context, repositoryID string) error

DisconnectRepo calls POST /v1/repos/{repositoryID}/disconnect to notify the API that this CLI is no longer syncing. Best-effort - callers should proceed with local cleanup even if this fails (offline, unauthenticated, etc.).

func EffectiveEndpoint

func EffectiveEndpoint() string

EffectiveEndpoint returns the backend endpoint for auth and remote calls.

func ForceRefresh

func ForceRefresh(ctx context.Context) (string, error)

ForceRefresh refreshes the stored session and returns the new access token.

func IsAPIKeyAuth

func IsAPIKeyAuth() bool

IsAPIKeyAuth returns true if the token came from SEMANTICA_API_KEY.

func OpenBrowser

func OpenBrowser(url string) error

OpenBrowser opens the given URL in the user's default browser. Best-effort - returns an error if the browser cannot be opened.

func RevokeSession

func RevokeSession(ctx context.Context, accessToken string) error

RevokeSession asks the backend to invalidate the current session.

func SaveCredentials

func SaveCredentials(c *Credentials) error

SaveCredentials writes credentials to secure storage first, falling back to file storage only if the keyring service is genuinely unavailable. If the keyring is reachable but save fails (locked, access denied), the error is returned - credentials are not silently downgraded to plaintext.

Types

type AccessRequestResponse

type AccessRequestResponse struct {
	WorkspaceName string `json:"workspace_name"`
}

AccessRequestResponse is the response from POST /v1/workspaces/access-requests.

func RequestWorkspaceAccess

func RequestWorkspaceAccess(ctx context.Context, remoteURL, repositoryID string) (*AccessRequestResponse, error)

RequestWorkspaceAccess creates an access request for the repo's workspace.

type AuthState

type AuthState struct {
	Authenticated bool   // true if auth is configured for the current endpoint
	Source        string // "api_key", "session", or ""
	Email         string // from credentials, empty for API key auth
	Endpoint      string // the endpoint this session is pinned to
	EndpointMatch bool   // true if stored endpoint matches effective endpoint
	StorageError  string // non-empty if credential storage itself failed
}

AuthState describes the effective local authentication state.

func GetAuthState

func GetAuthState() AuthState

GetAuthState reports auth state without refreshing or making network calls.

type ConnectRepoResponse

type ConnectRepoResponse struct {
	Outcome               string `json:"outcome"`
	RepositoryID          string `json:"repository_id,omitempty"`
	Message               string `json:"message"`
	GithubAppRecommended  bool   `json:"github_app_recommended,omitempty"`
	GitlabWebhookRequired bool   `json:"gitlab_webhook_required,omitempty"`
	GitlabWebhookURL      string `json:"gitlab_webhook_url,omitempty"`
	GitlabWebhookSecret   string `json:"gitlab_webhook_secret,omitempty"`
	GitlabWebhookReason   string `json:"gitlab_webhook_reason,omitempty"`
	Provider              string `json:"provider,omitempty"`
	AuthURL               string `json:"auth_url,omitempty"`
	State                 string `json:"state,omitempty"`
	Error                 string `json:"error,omitempty"`

	// Conflict metadata (repo_belongs_to_other_workspace only).
	WorkspaceName          string `json:"workspace_name,omitempty"`
	RequestAccessSupported bool   `json:"request_access_supported,omitempty"`
	ExistingRequestStatus  string `json:"existing_request_status,omitempty"`
}

ConnectRepoResponse is the structured response from POST /v1/repos/connect and POST /v1/repos/connect/poll.

func ConnectRepo

func ConnectRepo(ctx context.Context, remoteURL, provider string) (*ConnectRepoResponse, error)

ConnectRepo calls POST /v1/repos/connect and decodes the structured outcome.

func PollConnectRepo

func PollConnectRepo(ctx context.Context, state string, interval int) (*ConnectRepoResponse, error)

PollConnectRepo calls POST /v1/repos/connect/poll until the flow completes.

type Credentials

type Credentials struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token"`
	ExpiresAt    int64  `json:"expires_at"` // unix seconds
	Email        string `json:"email,omitempty"`
	Endpoint     string `json:"endpoint"`
}

Credentials holds the user's authentication tokens.

func LoadCredentials

func LoadCredentials() (*Credentials, error)

LoadCredentials reads credentials from secure storage first, then falls back to file storage. It also migrates file-backed credentials into secure storage when possible. Returns (nil, nil) if no credentials exist in either store.

func (*Credentials) IsExpired

func (c *Credentials) IsExpired() bool

IsExpired returns true if the access token has expired.

type LoginResponse

type LoginResponse struct {
	URL   string `json:"url"`   // full OAuth authorize URL
	State string `json:"state"` // correlation key for polling
}

LoginResponse is returned by the backend with the OAuth URL and state.

func RequestLogin

func RequestLogin(ctx context.Context, endpoint, provider string) (*LoginResponse, error)

RequestLogin starts the OAuth login flow for the given provider.

type MeResponse

type MeResponse struct {
	Email              string `json:"email"`
	WorkspaceName      string `json:"workspace_name,omitempty"`
	WorkspaceTierCode  string `json:"workspace_tier_code,omitempty"`
	WorkspaceTierTitle string `json:"workspace_tier_title,omitempty"`
}

func Me

func Me(ctx context.Context) (*MeResponse, error)

Me fetches the current authenticated user's workspace summary.

type TokenResponse

type TokenResponse struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token"`
	ExpiresIn    int    `json:"expires_in"`
	Email        string `json:"email,omitempty"`
	Error        string `json:"error,omitempty"` // "authorization_pending", "expired_token"
}

TokenResponse is returned by the backend on token exchange (OAuth callback or refresh).

func PollForToken

func PollForToken(ctx context.Context, endpoint, state string, interval int) (*TokenResponse, error)

PollForToken polls the backend until the user completes OAuth authorization, the state expires, or the context is cancelled.