auth

Documentation

Index

• Constants
• Variables
• func BuildAuthURL(cfg *config.Config, codeChallenge, state string, scopes []string) string
• func GenerateCodeChallenge(verifier string) string
• func GenerateCodeVerifier() (string, error)
• func GenerateState() (string, error)
• func HasAnyScope(token *Token, scopes ...string) bool
• func HasScope(token *Token, scope string) bool
• func OverrideTokenURL(u string) func()
• func SaveToken(cfg *config.Config, token *Token) error
• func StartCallbackServer(port int, state string) (string, error)
• func StartCallbackServerAsync(port int, state string) (<-chan CallbackResult, error)
• func TokenPath(cfg *config.Config) string
• type CallbackResult
• type Token
  • func ExchangeCode(ctx context.Context, cfg *config.Config, code, codeVerifier string) (*Token, error)
  • func GetValidToken(cfg *config.Config) (*Token, error)
  • func LoadToken(cfg *config.Config) (*Token, error)
  • func RefreshAccessToken(ctx context.Context, cfg *config.Config, token *Token) (*Token, error)
  • func (t *Token) IsExpired() bool
  • func (t *Token) SetExpiryFromExpiresIn()

Constants

const (
	ScopeInvoiceRead  = "mfc/invoice/data.read"
	ScopeInvoiceWrite = "mfc/invoice/data.write"
)

Invoice scope constants for callers that want symbolic references rather than hard-coded strings.

Variables

var AllScopes = []string{
	"mfc/accounting/offices.read",
	"mfc/accounting/accounts.read",
	"mfc/accounting/departments.read",
	"mfc/accounting/journal.read",
	"mfc/accounting/report.read",
	"mfc/accounting/taxes.read",
	"mfc/accounting/trade_partners.read",
	"mfc/accounting/connected_account.read",
	"mfc/accounting/journal.write",
	"mfc/accounting/voucher.write",
	"mfc/accounting/trade_partners.write",
	"mfc/accounting/transaction.write",
	"mfc/invoice/data.read",
	"mfc/invoice/data.write",
}

AllScopes contains all available scopes including write permissions.

`mfc/invoice/data.read` and `mfc/invoice/data.write` cover the MoneyForward Cloud Invoice API v3. Per the official scope guide, `data.write` permits both reference and update access (GET/POST/PUT/ DELETE), while `data.read` is read-only.

Note that Token.Scopes records the scopes *requested* during login, not necessarily the scopes the OAuth provider granted. Preflight checks based on Token.Scopes should therefore be treated as a hint rather than authoritative — the API's `insufficient_scope` response remains the final source of truth.

var DefaultScopes = []string{
	"mfc/accounting/offices.read",
	"mfc/accounting/accounts.read",
	"mfc/accounting/departments.read",
	"mfc/accounting/journal.read",
	"mfc/accounting/report.read",
	"mfc/accounting/taxes.read",
	"mfc/accounting/trade_partners.read",
	"mfc/accounting/connected_account.read",
}

DefaultScopes contains read-only scopes for MoneyForward Accounting API.

Functions

func BuildAuthURL

func BuildAuthURL(cfg *config.Config, codeChallenge, state string, scopes []string) string

BuildAuthURL constructs the OAuth 2.0 authorization URL with PKCE parameters.

func GenerateCodeChallenge

func GenerateCodeChallenge(verifier string) string

GenerateCodeChallenge derives a PKCE code challenge from a verifier (SHA256 + base64url).

func GenerateCodeVerifier

func GenerateCodeVerifier() (string, error)

GenerateCodeVerifier generates a PKCE code verifier (32 random bytes, base64url encoded).

func GenerateState

func GenerateState() (string, error)

GenerateState generates a random state parameter (16 random bytes, hex encoded).

func HasAnyScope

func HasAnyScope(token *Token, scopes ...string) bool

HasAnyScope reports whether the token has at least one of the given scopes. Returns false for nil token, empty token.Scopes, or empty scopes argument.

func HasScope

func HasScope(token *Token, scope string) bool

HasScope reports whether the token's stored scope list contains the given scope (case-sensitive after trimming surrounding whitespace). A nil token returns false. A token with an empty Scopes slice also returns false — callers wanting "unknown" semantics should check len(token.Scopes) themselves and skip the preflight.

func OverrideTokenURL

func OverrideTokenURL(u string) func()

OverrideTokenURL replaces the token endpoint and returns a restore function. Intended for use in tests from external packages.

func SaveToken

func SaveToken(cfg *config.Config, token *Token) error

SaveToken writes a token to disk atomically with restricted permissions.

func StartCallbackServer

func StartCallbackServer(port int, state string) (string, error)

StartCallbackServer starts a local HTTP server that waits for the OAuth callback. It verifies the state parameter and returns the authorization code.

func StartCallbackServerAsync

func StartCallbackServerAsync(port int, state string) (<-chan CallbackResult, error)

StartCallbackServerAsync starts the listener and returns a channel that delivers the result. The server is started before returning, so the caller can open the browser after this call.

func TokenPath

func TokenPath(cfg *config.Config) string

TokenPath returns the file path for the persisted token.

Types

type CallbackResult

type CallbackResult struct {
	Code string
	Err  error
}

CallbackResult holds the result from the OAuth callback.

type Token

type Token struct {
	AccessToken  string    `json:"access_token"`
	RefreshToken string    `json:"refresh_token"`
	TokenType    string    `json:"token_type"`
	ExpiresIn    int       `json:"expires_in,omitempty"`
	Expiry       time.Time `json:"expiry"`
	Scopes       []string  `json:"scopes"`
}

Token represents an OAuth 2.0 token.

func ExchangeCode

func ExchangeCode(ctx context.Context, cfg *config.Config, code, codeVerifier string) (*Token, error)

ExchangeCode exchanges an authorization code for an access token.

func GetValidToken

func GetValidToken(cfg *config.Config) (*Token, error)

GetValidToken loads a token, refreshes it if expired, and returns a valid token. It uses file locking to coordinate concurrent processes.

func LoadToken

func LoadToken(cfg *config.Config) (*Token, error)

LoadToken reads a token from disk.

func RefreshAccessToken

func RefreshAccessToken(ctx context.Context, cfg *config.Config, token *Token) (*Token, error)

RefreshAccessToken exchanges a refresh token for a new access token.

func (*Token) IsExpired

func (t *Token) IsExpired() bool

IsExpired reports whether the token has expired (with a 30-second buffer).

func (*Token) SetExpiryFromExpiresIn

func (t *Token) SetExpiryFromExpiresIn()

SetExpiryFromExpiresIn computes the Expiry field from ExpiresIn (seconds).