Cloud Authentication

Integration with Gatsby Cloud for authentication, user management, and cloud service access. These features are experimental and require the GATSBY_EXPERIMENTAL_CLOUD_CLI environment variable.

Capabilities

Login to Gatsby Cloud

Authenticate with Gatsby Cloud using browser-based OAuth flow.

/**
 * Authenticate with Gatsby Cloud
 * Opens browser for OAuth authentication and stores access token
 */
gatsby login

Usage Examples:

# Enable cloud CLI features
export GATSBY_EXPERIMENTAL_CLOUD_CLI=true

# Login to Gatsby Cloud
gatsby login

Authentication Flow:

1. Creates authentication ticket with Gatsby Cloud
2. Opens default browser to Gatsby Cloud login page
3. User authenticates via browser OAuth flow
4. CLI polls for authentication completion
5. Stores access token locally for future use
6. Confirms successful authentication

Authentication Process:

/**
 * Authentication ticket system
 * Temporary session for secure browser-based authentication
 */
interface AuthenticationTicket {
  ticketId: string;         // Unique ticket identifier
  verified: boolean;        // Authentication completion status
  token?: string | null;    // Access token (when verified)
  expiration?: string | null; // Token expiration date
}

/**
 * Create authentication ticket
 * @returns Promise resolving to ticket ID
 */
function createTicket(): Promise<string>;

/**
 * Check ticket verification status
 * @param ticketId - Ticket identifier to check
 * @returns Promise resolving to ticket status
 */
function getTicket(ticketId: string): Promise<AuthenticationTicket>;

Browser Integration:

• Automatically opens default browser
• Provides fallback URL for manual copying
• Handles authentication redirects
• Manages OAuth callback processing

Logout from Gatsby Cloud

Remove stored authentication credentials and sign out of Gatsby Cloud services.

/**
 * Sign out of Gatsby Cloud
 * Removes stored access token and clears authentication state
 */
gatsby logout

Usage Examples:

# Logout from Gatsby Cloud
gatsby logout

Logout Process:

1. Removes stored access token
2. Clears token expiration data
3. Invalidates local authentication state
4. Confirms successful logout

Check Current User

Display information about the currently authenticated Gatsby Cloud user.

/**
 * Display current user information
 * Shows username of authenticated Gatsby Cloud user
 */
gatsby whoami

Usage Examples:

# Check current user
gatsby whoami

# Example output
# john.doe@example.com

User Information Retrieval:

/**
 * Fetch current user information from Gatsby Cloud
 * @param token - Access token for authentication
 * @returns Promise resolving to username
 */
function getUsername(token: string): Promise<string>;

GraphQL Query for User Data:

query {
  currentUser {
    name
  }
}

Token Management

Secure storage and management of authentication tokens.

/**
 * Token management functions
 * Secure storage of authentication credentials
 */
interface TokenManager {
  getToken(): Promise<string>;                      // Retrieve stored token
  setToken(token: string | null, expiration: string): void;  // Store token with expiration
}

/**
 * Token storage structure
 */
interface TokenStorage {
  token: string | null;      // Access token
  expiration: string;        /* Expiration date*/
}

Token Features:

• Secure local storage using Gatsby config store
• Automatic expiration checking
• Token refresh warnings
• Secure token transmission to Gatsby Cloud API

Configuration Storage:

• Tokens stored in Gatsby's configuration system
• Encrypted storage on local filesystem
• Cross-platform compatibility
• Automatic cleanup on logout

Error Handling

Comprehensive error handling for authentication operations.

Login Errors:

/**
 * Authentication error types
 */
type AuthenticationError = 
  | "NetworkError"           // Cannot connect to Gatsby Cloud
  | "BrowserError"          // Cannot open browser
  | "TimeoutError"          // Authentication timeout
  | "TokenError"            // Invalid or expired token
  | "UserCancelledError";   // User cancelled authentication

Common Error Scenarios:

• Network connectivity issues
• Browser launch failures
• Authentication timeouts
• Invalid or expired tokens
• User cancellation of auth flow

Error Messages:

# Network error example
We had trouble connecting to Gatsby Cloud to create a login session.
Please try again later, and if it continues to have trouble connecting file an issue.

# Already logged in
You are already logged in!

# Not logged in (whoami)
You are not currently logged in!

# Token expired warning
Your token has expired, you may need to login again

Configuration Requirements

Setup and configuration for Gatsby Cloud CLI features.

Environment Variables:

/**
 * Required environment configuration
 */
interface CloudConfiguration {
  GATSBY_EXPERIMENTAL_CLOUD_CLI: string;  // Enable cloud features ("true")
}

Setup Examples:

# Enable cloud CLI features permanently
echo 'export GATSBY_EXPERIMENTAL_CLOUD_CLI=true' >> ~/.bashrc
source ~/.bashrc

# Enable for current session only
export GATSBY_EXPERIMENTAL_CLOUD_CLI=true

# Enable for single command
GATSBY_EXPERIMENTAL_CLOUD_CLI=true gatsby login

Feature Availability:

• Login/logout commands only available with environment variable
• Commands gracefully hidden when not enabled
• No impact on other Gatsby CLI functionality
• Backward compatibility maintained

API Integration

Integration with Gatsby Cloud services and APIs.

Service Endpoints:

/**
 * Gatsby Cloud service endpoints
 */
interface GatsbyCloudEndpoints {
  authService: "https://auth.gatsbyjs.com";     // Authentication service
  apiService: "https://api.gatsbyjs.com";      // GraphQL API service
  webService: "https://gatsbyjs.com";          // Web interface
}

API Authentication:

• Bearer token authentication
• RESTful authentication endpoints
• GraphQL API for user data
• Secure HTTPS communication

Authentication URLs:

• Ticket creation: POST /auth/tickets/create
• Ticket verification: GET /auth/tickets/{ticketId}
• User dashboard: /dashboard/login?authType=EXTERNAL_AUTH&ticketId={id}

Security Considerations

Security best practices for cloud authentication.

Token Security:

• Tokens stored locally, never transmitted in plain text
• Automatic expiration checking and warnings
• Secure token storage using OS-level encryption
• Token invalidation on logout

Network Security:

• HTTPS-only communication with Gatsby Cloud
• Certificate validation and pinning
• Protection against man-in-the-middle attacks
• Secure redirect URL validation

Browser Security:

• Secure OAuth callback handling
• Protection against CSRF attacks
• Automatic cleanup of temporary authentication data
• Safe browser launch with fallback options

Development Workflow Integration

Integration with common Gatsby development workflows.

CI/CD Integration:

• Environment variable configuration
• Automated authentication for deployments
• Token management in CI environments
• Secure credential storage

Team Collaboration:

• Individual user authentication
• Shared project access through Gatsby Cloud
• Role-based permissions and access control
• Team member management through web interface