@dotsetlabs/bellwether 0.10.0

package/dist/cloud/auth.js

@@ -0,0 +1,374 @@
+/**
+ * Authentication module for Bellwether Cloud.
+ *
+ * Handles session storage, retrieval, and management.
+ * Sessions are stored in ~/.bellwether/session.json with restricted permissions.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, statSync, chmodSync } from 'fs';
+import { join } from 'path';
+import { homedir, platform } from 'os';
+import { URLS, PATHS, PATTERNS, CLI_SECURITY } from '../constants.js';
+import { isLocalhost } from '../utils/index.js';
+import * as output from '../cli/output.js';
+/**
+ * Directory for bellwether configuration.
+ */
+export const CONFIG_DIR = join(homedir(), PATHS.CONFIG_DIR);
+/**
+ * Path to session file.
+ */
+export const SESSION_FILE = join(CONFIG_DIR, PATHS.SESSION_FILE);
+/**
+ * Environment variable name for session token.
+ */
+export const SESSION_ENV_VAR = 'BELLWETHER_SESSION';
+/**
+ * Environment variable name for API base URL.
+ */
+export const BASE_URL_ENV_VAR = 'BELLWETHER_API_URL';
+/**
+ * Environment variable name for team ID override.
+ */
+export const TEAM_ID_ENV_VAR = 'BELLWETHER_TEAM_ID';
+/**
+ * Session token prefix for validation.
+ */
+export const SESSION_PREFIX = CLI_SECURITY.SESSION_PREFIX;
+/**
+ * Mock session prefix for development.
+ */
+export const MOCK_SESSION_PREFIX = CLI_SECURITY.MOCK_SESSION_PREFIX;
+/**
+ * Session token pattern: sess_ followed by 64 hex characters.
+ * Mock sessions use sess_mock_ prefix with username and hex characters.
+ * Format: sess_mock_<username>_<hex>
+ */
+const SESSION_TOKEN_PATTERN = PATTERNS.SESSION_TOKEN;
+const MOCK_SESSION_TOKEN_PATTERN = PATTERNS.MOCK_SESSION_TOKEN;
+/**
+ * Ensure the config directory exists.
+ */
+export function ensureConfigDir() {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    }
+}
+/**
+ * Verify and fix session file permissions.
+ * On Unix systems, ensures file is only readable by owner (0600).
+ * Returns false if permissions could not be verified/fixed.
+ */
+function verifySessionPermissions() {
+    // Skip permission checks on Windows (Windows has different ACL system)
+    if (platform() === 'win32') {
+        return true;
+    }
+    try {
+        if (!existsSync(SESSION_FILE)) {
+            return true; // No file to check
+        }
+        const stats = statSync(SESSION_FILE);
+        const mode = stats.mode & 0o777;
+        // Check if permissions are too permissive (anyone other than owner can read)
+        if (mode & 0o077) {
+            // Try to fix permissions
+            try {
+                chmodSync(SESSION_FILE, 0o600);
+                return true;
+            }
+            catch {
+                // Could not fix permissions
+                return false;
+            }
+        }
+        return true;
+    }
+    catch (error) {
+        // If we can't stat the file, there's a real problem
+        output.warn(`Warning: Could not verify session file permissions: ${error instanceof Error ? error.message : error}`);
+        return false;
+    }
+}
+/**
+ * Get the stored session.
+ * Returns null if no session exists, session is expired, or file is corrupted.
+ */
+export function getStoredSession() {
+    if (!existsSync(SESSION_FILE)) {
+        return null;
+    }
+    // Verify file permissions before reading sensitive data
+    const permissionsOk = verifySessionPermissions();
+    if (!permissionsOk) {
+        // Permissions are insecure and couldn't be fixed - refuse to use session
+        output.error('Error: Session file has insecure permissions. Please fix with:');
+        output.error(`  chmod 600 ${SESSION_FILE}`);
+        return null;
+    }
+    try {
+        const content = readFileSync(SESSION_FILE, 'utf-8');
+        const session = JSON.parse(content);
+        // Validate and check if session is expired
+        if (!session.expiresAt) {
+            output.warn('Warning: Session file missing expiration date, clearing it.');
+            clearSession();
+            return null;
+        }
+        const expirationDate = new Date(session.expiresAt);
+        if (isNaN(expirationDate.getTime())) {
+            output.warn('Warning: Session file has invalid expiration date, clearing it.');
+            clearSession();
+            return null;
+        }
+        if (expirationDate <= new Date()) {
+            // Session expired, clear it
+            clearSession();
+            return null;
+        }
+        return session;
+    }
+    catch {
+        // If file is corrupted, log and return null
+        output.warn('Warning: Session file is corrupted, clearing it.');
+        clearSession();
+        return null;
+    }
+}
+/**
+ * Save session to disk.
+ * File is created with 0600 permissions (owner read/write only).
+ */
+export function saveSession(session) {
+    ensureConfigDir();
+    writeFileSync(SESSION_FILE, JSON.stringify(session, null, 2), { mode: 0o600 });
+}
+/**
+ * Clear the stored session.
+ */
+export function clearSession() {
+    if (existsSync(SESSION_FILE)) {
+        try {
+            unlinkSync(SESSION_FILE);
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+}
+/**
+ * Get the session token.
+ *
+ * Priority:
+ * 1. BELLWETHER_SESSION environment variable
+ * 2. Stored session in ~/.bellwether/session.json
+ */
+export function getSessionToken() {
+    // Check environment variable first
+    const envSession = process.env[SESSION_ENV_VAR];
+    if (envSession) {
+        return envSession;
+    }
+    // Fall back to stored session
+    const session = getStoredSession();
+    return session?.sessionToken;
+}
+/**
+ * Get the API base URL.
+ *
+ * Priority:
+ * 1. BELLWETHER_API_URL environment variable
+ * 2. Default: https://api.bellwether.sh
+ *
+ * Security: Validates that custom URLs use HTTPS (except localhost for development).
+ */
+export function getBaseUrl() {
+    // Check environment variable first
+    const envUrl = process.env[BASE_URL_ENV_VAR];
+    if (envUrl) {
+        // Validate URL format and security
+        try {
+            const url = new URL(envUrl);
+            // Allow HTTP only for localhost (development)
+            if (url.protocol !== 'https:' && !isLocalhost(url.hostname)) {
+                output.warn(`Warning: ${BASE_URL_ENV_VAR} uses insecure HTTP protocol.`);
+                output.warn('HTTPS is required for production use to protect authentication tokens.');
+                output.warn('Use HTTPS or localhost for secure communication.\n');
+            }
+            return envUrl;
+        }
+        catch {
+            output.warn(`Warning: Invalid URL in ${BASE_URL_ENV_VAR}: ${envUrl}`);
+            output.warn('Falling back to default API URL.\n');
+            return URLS.CLOUD_API;
+        }
+    }
+    // Return default
+    return URLS.CLOUD_API;
+}
+/**
+ * Check if a session token appears valid (strict format check).
+ * Validates against exact patterns to prevent injection.
+ */
+export function isValidSessionFormat(token) {
+    return SESSION_TOKEN_PATTERN.test(token) || MOCK_SESSION_TOKEN_PATTERN.test(token);
+}
+/**
+ * Check if a session token is a mock session (for development).
+ */
+export function isMockSession(token) {
+    return token.startsWith(MOCK_SESSION_PREFIX);
+}
+/**
+ * Check if currently authenticated.
+ */
+export function isAuthenticated() {
+    const token = getSessionToken();
+    return token !== undefined && isValidSessionFormat(token);
+}
+/**
+ * Get the active team ID.
+ *
+ * Priority:
+ * 1. BELLWETHER_TEAM_ID environment variable
+ * 2. Team ID from project link (if in a linked project directory)
+ * 3. Active team ID from stored session
+ */
+export function getTeamId(projectDir = process.cwd()) {
+    // Check environment variable first (for CI/CD)
+    const envTeamId = process.env[TEAM_ID_ENV_VAR];
+    if (envTeamId) {
+        return envTeamId;
+    }
+    // Check project link for project-specific team
+    const projectLink = getLinkedProject(projectDir);
+    if (projectLink?.teamId) {
+        return projectLink.teamId;
+    }
+    // Fall back to session's active team
+    const session = getStoredSession();
+    return session?.activeTeamId;
+}
+/**
+ * Get the active team details.
+ * Returns the full team object if available.
+ */
+export function getActiveTeam(projectDir = process.cwd()) {
+    const teamId = getTeamId(projectDir);
+    if (!teamId) {
+        return undefined;
+    }
+    const session = getStoredSession();
+    return session?.teams?.find(t => t.id === teamId);
+}
+/**
+ * Get all teams from the stored session.
+ */
+export function getSessionTeams() {
+    const session = getStoredSession();
+    return session?.teams ?? [];
+}
+/**
+ * Set the active team in the stored session.
+ * Returns true if successful, false if team not found in session.
+ */
+export function setActiveTeam(teamId) {
+    const session = getStoredSession();
+    if (!session) {
+        return false;
+    }
+    // Verify the team exists in the session
+    const teamExists = session.teams?.some(t => t.id === teamId);
+    if (!teamExists) {
+        return false;
+    }
+    // Update the active team
+    session.activeTeamId = teamId;
+    saveSession(session);
+    return true;
+}
+/**
+ * Update the session token in the stored session.
+ * Called when the server rotates the token and returns a new one.
+ *
+ * @param newToken - The new session token from the server
+ * @returns Promise that resolves when the session is updated
+ */
+export async function updateSessionToken(newToken) {
+    const session = getStoredSession();
+    if (!session) {
+        // No session to update - this shouldn't happen in normal flow
+        return;
+    }
+    // Validate the new token format
+    if (!isValidSessionFormat(newToken)) {
+        throw new Error('Invalid session token format received from server');
+    }
+    // Update the token and record when it was rotated
+    session.sessionToken = newToken;
+    session.tokenRotatedAt = new Date().toISOString();
+    saveSession(session);
+}
+/**
+ * Directory name for per-project bellwether config.
+ */
+export const PROJECT_CONFIG_DIR = '.bellwether';
+/**
+ * File name for project link configuration.
+ */
+export const LINK_FILE = 'link.json';
+/**
+ * Get the project link file path for a given directory.
+ */
+export function getLinkFilePath(projectDir = process.cwd()) {
+    return join(projectDir, PROJECT_CONFIG_DIR, LINK_FILE);
+}
+/**
+ * Get the linked project for the current directory.
+ */
+export function getLinkedProject(projectDir = process.cwd()) {
+    const linkFile = getLinkFilePath(projectDir);
+    if (!existsSync(linkFile)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(linkFile, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save a project link for the current directory.
+ */
+export function saveProjectLink(link, projectDir = process.cwd()) {
+    const configDir = join(projectDir, PROJECT_CONFIG_DIR);
+    if (!existsSync(configDir)) {
+        mkdirSync(configDir, { recursive: true });
+    }
+    const linkFile = getLinkFilePath(projectDir);
+    writeFileSync(linkFile, JSON.stringify(link, null, 2));
+}
+/**
+ * Remove the project link for the current directory.
+ */
+export function removeProjectLink(projectDir = process.cwd()) {
+    const linkFile = getLinkFilePath(projectDir);
+    if (!existsSync(linkFile)) {
+        return false;
+    }
+    try {
+        unlinkSync(linkFile);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if the current directory is linked to a project.
+ */
+export function isLinked(projectDir = process.cwd()) {
+    return getLinkedProject(projectDir) !== null;
+}
+//# sourceMappingURL=auth.js.map

package/dist/cloud/client.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Cloud client factory.
+ *
+ * Creates the appropriate cloud client implementation based on configuration.
+ * Supports:
+ * - MockCloudClient (local development/testing)
+ * - HttpCloudClient (production API)
+ */
+import type { BellwetherCloudClient, CloudConfig } from './types.js';
+/**
+ * Create a cloud client with the given configuration.
+ *
+ * If no session token is provided, attempts to get one from environment/storage.
+ * Automatically selects mock client for development or HTTP client for production.
+ */
+export declare function createCloudClient(config?: Partial<CloudConfig>): BellwetherCloudClient;
+/**
+ * Create a cloud client with explicit session token.
+ *
+ * Convenience function for when you already have a session token.
+ */
+export declare function createCloudClientWithSession(sessionToken: string): BellwetherCloudClient;
+export type { BellwetherCloudClient, CloudConfig } from './types.js';
+//# sourceMappingURL=client.d.ts.map

package/dist/cloud/client.js

@@ -0,0 +1,65 @@
+/**
+ * Cloud client factory.
+ *
+ * Creates the appropriate cloud client implementation based on configuration.
+ * Supports:
+ * - MockCloudClient (local development/testing)
+ * - HttpCloudClient (production API)
+ */
+import { MockCloudClient } from './mock-client.js';
+import { HttpCloudClient } from './http-client.js';
+import { getSessionToken, getBaseUrl, isMockSession, getTeamId } from './auth.js';
+import { TIMEOUTS } from '../constants.js';
+/**
+ * Create a cloud client with the given configuration.
+ *
+ * If no session token is provided, attempts to get one from environment/storage.
+ * Automatically selects mock client for development or HTTP client for production.
+ */
+export function createCloudClient(config) {
+    const sessionToken = config?.sessionToken ?? getSessionToken();
+    const baseUrl = config?.baseUrl ?? getBaseUrl();
+    const timeout = config?.timeout ?? TIMEOUTS.CLOUD_API;
+    // Determine which client to use
+    const useMock = shouldUseMockClient(sessionToken);
+    if (useMock) {
+        return new MockCloudClient(sessionToken);
+    }
+    // Use HTTP client for production
+    if (!sessionToken) {
+        throw new Error('Session required for HTTP client. Run `bellwether login` first.');
+    }
+    const teamId = getTeamId();
+    return new HttpCloudClient(baseUrl, sessionToken, timeout, teamId);
+}
+/**
+ * Determine if we should use the mock client.
+ *
+ * Uses mock client when:
+ * - Session is a mock session (sess_mock_*)
+ * - No session is provided (unauthenticated mode)
+ *
+ * Uses HTTP client when:
+ * - A real session is provided (even for localhost - allows local server testing)
+ */
+function shouldUseMockClient(sessionToken) {
+    // Use mock if session is a mock session
+    if (sessionToken && isMockSession(sessionToken)) {
+        return true;
+    }
+    // Use mock if no session (unauthenticated mock mode)
+    if (!sessionToken) {
+        return true;
+    }
+    // Use HTTP client for real sessions (works with localhost or production)
+    return false;
+}
+/**
+ * Create a cloud client with explicit session token.
+ *
+ * Convenience function for when you already have a session token.
+ */
+export function createCloudClientWithSession(sessionToken) {
+    return createCloudClient({ sessionToken });
+}
+//# sourceMappingURL=client.js.map

package/dist/cloud/http-client.d.ts

@@ -0,0 +1,38 @@
+/**
+ * HTTP cloud client for production API.
+ *
+ * Makes real HTTP requests to the Bellwether Cloud API.
+ * Handles automatic session token rotation when the server returns
+ * a new token via the X-Rotated-Session-Token header.
+ */
+import type { BellwetherCloudClient, CloudUser, Project, BaselineVersion, UploadResult, DiffSummary, BellwetherBaseline, BadgeInfo, CloudVerificationResult, VerificationSubmissionResult } from './types.js';
+/**
+ * HTTP cloud client implementation.
+ */
+export declare class HttpCloudClient implements BellwetherCloudClient {
+    private baseUrl;
+    private sessionToken;
+    private teamId?;
+    private timeout;
+    constructor(baseUrl: string, sessionToken: string, timeout?: number, teamId?: string);
+    /**
+     * Make an authenticated request.
+     * Handles automatic session token rotation when the server returns
+     * a new token via the X-Rotated-Session-Token header.
+     */
+    private request;
+    isAuthenticated(): boolean;
+    whoami(): Promise<CloudUser | null>;
+    listProjects(): Promise<Project[]>;
+    createProject(name: string, serverCommand: string): Promise<Project>;
+    getProject(projectId: string): Promise<Project | null>;
+    deleteProject(projectId: string): Promise<void>;
+    uploadBaseline(projectId: string, baseline: BellwetherBaseline): Promise<UploadResult>;
+    getHistory(projectId: string, limit?: number): Promise<BaselineVersion[]>;
+    getBaseline(baselineId: string): Promise<BellwetherBaseline | null>;
+    getDiff(projectId: string, fromVersion: number, toVersion: number): Promise<DiffSummary>;
+    getLatestDiff(projectId: string): Promise<DiffSummary | null>;
+    getBadgeInfo(projectId: string): Promise<BadgeInfo | null>;
+    submitVerification(projectId: string, result: CloudVerificationResult, report?: Record<string, unknown>): Promise<VerificationSubmissionResult>;
+}
+//# sourceMappingURL=http-client.d.ts.map