🔐 Authentication Flow

This page outlines how authentication is handled in the EVE Companion App using OAuth2 and EVE Online's SSO (Single Sign-On) system. We support both in-app browser login and persistent token storage for user reauthentication.

---

🌐 ESI + OAuth2 Overview

The EVE Swagger Interface (ESI) uses OAuth2 to secure personal endpoints:

• Character location
• Wallet transactions
• Skills & queue
• Fleet join/leave
• Contacts and corp history

Authentication is required for any personalized data access.

---

🔑 OAuth2 Providers

We support multiple methods depending on the context:

Method	Purpose
simple-oauth2	Token flow and refresh in main process
oidc-client-ts	Optional browser-based login fallback

---

🧭 Flow Overview

graph TD
A[User Launches App] --> B[Check for Stored Token]
B -->|Valid| D[Access ESI Endpoints]
B -->|Missing/Expired| C[Begin Auth Flow]
C --> E[Redirect to CCP Login Page]
E --> F[User Logs In]
F --> G[Receive Authorization Code]
G --> H[Exchange for Access + Refresh Tokens]
H --> I[Store Tokens Securely]
I --> D

---

🛠 Token Storage

Tokens are stored using electron-store under a secure app-specific path:

store.set('auth.token', accessToken);
store.set('auth.refresh', refreshToken);

These are retrieved on launch and checked for expiration.

---

♻️ Refreshing Tokens

When a token is expired or nearing expiration, it is refreshed automatically using simple-oauth2:

const newToken = await client.refresh(refreshToken);
store.set('auth.token', newToken.access_token);

Refresh tokens are long-lived unless revoked manually.

---

🔐 Scope Handling

Each login request includes requested scopes. Examples:

• esi-location.read_location.v1
• esi-mail.read_mail.v1
• esi-wallet.read_character_wallet.v1

Scopes determine what ESI endpoints are accessible for that character.

---

👤 Multiple Characters (Planned)

• Users may authorize multiple characters
• Each character will have its own token object
• Switch between active characters via UI selector
• Tokens will be stored and refreshed per character

---

🚫 Logout and Token Revocation

To clear auth state:

store.delete('auth.token');
store.delete('auth.refresh');

Users may also revoke app access via the EVE Online SSO Portal.

---

📌 Summary

• OAuth2 is used to access private ESI endpoints
• Tokens are stored in electron-store and refreshed as needed
• Multiple auth methods and fallback login support planned
• Character switching and multi-token support in roadmap

---