@startanaicompany/cli 1.4.15 → 1.4.16

package/CLAUDE.md

@@ -395,6 +395,101 @@ saac deploy --force
 
 **Note:** The `--force` flag is defined in the CLI but not currently used by the API.
 
+### OTP-Based Login (NEW in 1.4.16)
+
+The login command now supports two authentication methods:
+
+**Method 1: Login with API Key (Fast Path)**
+```bash
+saac login -e user@example.com -k cw_abc123
+# → Immediate session token, no email verification needed
+```
+
+**Method 2: Login with OTP (Recovery Path)**
+```bash
+# Step 1: Request OTP
+saac login -e user@example.com
+# → Verification code sent to email (6 digits, 5-minute expiration)
+
+# Step 2: Verify OTP
+saac login -e user@example.com --otp 123456
+# → Session token created, user is now logged in
+```
+
+**Why This Feature?**
+
+Solves the **API key lockout problem**:
+- User loses API key
+- All sessions expire
+- Cannot login (no API key)
+- Cannot regenerate key (requires login)
+- **LOCKED OUT** ❌
+
+With OTP login:
+- User can always recover via email ✅
+- No support tickets needed ✅
+- Self-service account recovery ✅
+
+**Implementation Details:**
+
+The `login.js` command now has three modes:
+1. **API key login** - If `-k` flag provided (existing flow)
+2. **OTP request** - If no `-k` or `--otp` flag (new flow)
+3. **OTP verification** - If `--otp` flag provided (new flow)
+
+**Backend Requirements:**
+- `POST /api/v1/auth/login-otp` - Generate and send OTP
+- `POST /api/v1/auth/verify-otp` - Verify OTP and create session
+
+See `/data/sharedinfo/login-feature-update.md` for complete API specifications.
+
+### API Key Management (NEW in 1.4.16)
+
+Users can now regenerate their API keys if lost or compromised.
+
+**Commands:**
+
+```bash
+# Regenerate API key (requires authentication)
+saac keys regenerate
+# → Shows new API key (only once!)
+
+# Show API key info
+saac keys show
+# → Displays key prefix, created date, last used
+```
+
+**Recovery Flow:**
+
+```bash
+# 1. User loses API key but is not logged in
+saac login -e user@example.com
+# → OTP sent to email
+
+# 2. Verify OTP
+saac login -e user@example.com --otp 123456
+# → Logged in with session token
+
+# 3. Generate new API key
+saac keys regenerate
+# → New API key: cw_new_key_xyz...
+
+# 4. On next machine, use new API key
+saac login -e user@example.com -k cw_new_key_xyz...
+```
+
+**Security Notes:**
+- Regenerating API key invalidates the old key immediately
+- Existing session tokens remain valid (no disruption)
+- Email notification sent when key is regenerated
+- Full API key shown only once (must be saved)
+
+**Backend Requirements:**
+- `POST /api/v1/users/regenerate-key` - Generate new API key
+- `GET /api/v1/users/api-key` - Get API key info (optional)
+
+See `/data/sharedinfo/login-feature-update.md` for complete specifications.
+
 ### Init Command Implementation
 
 The `init` command links an existing SAAC application to the current directory.
@@ -493,19 +588,26 @@ The wrapper API expects Git repositories to be hosted on the StartAnAiCompany Gi
 - During registration, Gitea username can be auto-detected or manually provided
 - Applications reference repositories in the format: `git@git.startanaicompany.com:user/repo.git`
 
-## Current Status - Version 1.4.15
+## Current Status - Version 1.4.16
 
 ### Completed Features
 
 **Authentication & Sessions:**
 - ✅ `saac register` - Register with email only (git_username auto-detected from email)
-- ✅ `saac login` - Login with email + API key, receives 1-year session token
+- ✅ `saac login` - Two methods: API key (fast) or OTP (recovery)
+  - `saac login -e email -k api-key` - Login with API key
+  - `saac login -e email` - Request OTP via email
+  - `saac login -e email --otp code` - Verify OTP and login
 - ✅ `saac verify` - Email verification, shows FULL API key for user to save
 - ✅ `saac logout` - Logout from current device
 - ✅ `saac logout-all` - Revoke all sessions
 - ✅ `saac sessions` - List all active sessions
 - ✅ `saac whoami` - Show current user info
 
+**API Key Management (NEW in 1.4.16):**
+- ✅ `saac keys regenerate` - Generate new API key (invalidates old one)
+- ✅ `saac keys show` - Show API key information (prefix, created, last used)
+
 **Git OAuth (NEW in 1.4.0):**
 - ✅ `saac git connect [host]` - OAuth flow for Git authentication
 - ✅ `saac git list` - List connected Git accounts
@@ -706,4 +808,4 @@ Before publishing to npm:
 - `dotenv` - Environment variables
 - `open` - Open browser for OAuth (v8.4.2 for compatibility with chalk v4)
 
-**Version:** 1.4.15 (current)
+**Version:** 1.4.16 (current)

package/bin/saac.js

@@ -16,6 +16,7 @@ const verify = require('../src/commands/verify');
 const logout = require('../src/commands/logout');
 const logoutAll = require('../src/commands/logoutAll');
 const sessions = require('../src/commands/sessions');
+const keys = require('../src/commands/keys');
 const git = require('../src/commands/git');
 const init = require('../src/commands/init');
 const create = require('../src/commands/create');
@@ -56,7 +57,8 @@ program
   .command('login')
   .description('Login with existing account')
   .option('-e, --email <email>', 'Email address')
-  .option('-k, --api-key <key>', 'API key')
+  .option('-k, --api-key <key>', 'API key (for fast login)')
+  .option('--otp <code>', 'One-time password from email')
   .action(login);
 
 program
@@ -80,6 +82,22 @@ program
   .description('List all active sessions')
   .action(sessions);
 
+// API Key management
+const keysCommand = program
+  .command('keys')
+  .description('Manage API keys');
+
+keysCommand
+  .command('regenerate')
+  .description('Generate a new API key (invalidates old one)')
+  .action(keys.regenerate);
+
+keysCommand
+  .command('show')
+  .alias('info')
+  .description('Show API key information')
+  .action(keys.show);
+
 // Git OAuth commands
 const gitCommand = program
   .command('git')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startanaicompany/cli",
-  "version": "1.4.15",
+  "version": "1.4.16",
   "description": "Official CLI for StartAnAiCompany.com - Deploy AI recruitment sites with ease",
   "main": "src/index.js",
   "bin": {

package/src/commands/keys.js

@@ -0,0 +1,143 @@
+/**
+ * API Key management commands
+ */
+
+const api = require('../lib/api');
+const { getUser, isAuthenticated } = require('../lib/config');
+const logger = require('../lib/logger');
+const inquirer = require('inquirer');
+
+/**
+ * Regenerate API key
+ */
+async function regenerate() {
+  try {
+    // Must be authenticated (via session token)
+    if (!isAuthenticated()) {
+      logger.error('Not logged in');
+      logger.newline();
+      logger.info('You must be logged in to regenerate your API key');
+      logger.newline();
+      logger.info('Login using email verification:');
+      logger.log('  saac login -e <email>           # Request OTP');
+      logger.log('  saac login -e <email> --otp <code>  # Verify OTP');
+      process.exit(1);
+    }
+
+    const user = getUser();
+
+    logger.section('Regenerate API Key');
+    logger.newline();
+
+    logger.warn('This will generate a new API key and invalidate your current one.');
+    logger.warn('Your active session tokens will continue to work.');
+    logger.newline();
+
+    // Confirmation prompt
+    const { confirm } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirm',
+        message: 'Are you sure you want to regenerate your API key?',
+        default: false,
+      },
+    ]);
+
+    if (!confirm) {
+      logger.info('Cancelled');
+      return;
+    }
+
+    const spin = logger.spinner('Generating new API key...').start();
+
+    try {
+      const result = await api.regenerateApiKey();
+
+      spin.succeed('New API key generated!');
+
+      logger.newline();
+      logger.success('Your new API key:');
+      logger.newline();
+
+      // Show FULL API key (it's only shown once)
+      logger.field('API Key', result.api_key);
+
+      logger.newline();
+      logger.warn('Save this key securely. It will not be shown again.');
+      logger.newline();
+
+      logger.info('Your existing sessions remain active.');
+      logger.info('Use this new key for future logins or CI/CD.');
+      logger.newline();
+
+      logger.info('To login with the new key:');
+      logger.log(`  saac login -e ${user.email} -k ${result.api_key}`);
+
+    } catch (error) {
+      spin.fail('Failed to regenerate API key');
+      throw error;
+    }
+  } catch (error) {
+    logger.error(error.response?.data?.message || error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Show API key info (without revealing full key)
+ */
+async function show() {
+  try {
+    if (!isAuthenticated()) {
+      logger.error('Not logged in');
+      logger.newline();
+      logger.info('Login first:');
+      logger.log('  saac login -e <email>');
+      process.exit(1);
+    }
+
+    logger.section('API Key Information');
+    logger.newline();
+
+    const spin = logger.spinner('Fetching API key info...').start();
+
+    try {
+      const result = await api.getApiKeyInfo();
+
+      spin.succeed('API key info retrieved');
+
+      logger.newline();
+      logger.field('Key Prefix', result.key_prefix); // e.g., "cw_RJ1gH8..."
+      logger.field('Created', new Date(result.created_at).toLocaleDateString());
+      logger.field('Last Used', result.last_used_at
+        ? new Date(result.last_used_at).toLocaleString()
+        : 'Never');
+
+      logger.newline();
+      logger.info('Commands:');
+      logger.log('  saac keys regenerate    Generate new API key');
+      logger.log('  saac sessions           View active sessions');
+
+    } catch (error) {
+      spin.fail('Failed to fetch API key info');
+
+      // If endpoint doesn't exist yet, show helpful message
+      if (error.response?.status === 404) {
+        logger.newline();
+        logger.warn('API key info endpoint not available yet');
+        logger.info('You can still regenerate your key with:');
+        logger.log('  saac keys regenerate');
+      } else {
+        throw error;
+      }
+    }
+  } catch (error) {
+    logger.error(error.response?.data?.message || error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  regenerate,
+  show,
+};

package/src/commands/login.js

@@ -1,5 +1,7 @@
 /**
- * Login command
+ * Login command - Two methods:
+ * 1. With API key (fast): saac login -e email -k api_key
+ * 2. With OTP (recovery): saac login -e email, then saac login -e email --otp code
  */
 
 const inquirer = require('inquirer');
@@ -10,21 +12,23 @@ const logger = require('../lib/logger');
 
 async function login(options) {
   try {
-    // Require both email and API key flags (no interactive prompts)
-    if (!options.email || !options.apiKey) {
-      logger.error('Email and API key are required');
+    // Require email flag
+    if (!options.email) {
+      logger.error('Email is required');
       logger.newline();
       logger.info('Usage:');
-      logger.log('  saac login -e <email> -k <api-key>');
-      logger.log('  saac login --email <email> --api-key <api-key>');
+      logger.log('  saac login -e <email> -k <api-key>           # Login with API key');
+      logger.log('  saac login -e <email>                        # Request OTP via email');
+      logger.log('  saac login -e <email> --otp <code>           # Verify OTP and login');
       logger.newline();
-      logger.info('Example:');
-      logger.log('  saac login -e user@example.com -k cw_your_api_key');
+      logger.info('Examples:');
+      logger.log('  saac login -e user@example.com -k cw_abc123  # Fast login');
+      logger.log('  saac login -e user@example.com               # Send OTP to email');
+      logger.log('  saac login -e user@example.com --otp 123456  # Verify OTP');
       process.exit(1);
     }
 
     const email = options.email;
-    const apiKey = options.apiKey;
 
     // Validate email format
     if (!validator.isEmail(email)) {
@@ -33,46 +37,143 @@ async function login(options) {
     }
 
     logger.section('Login to StartAnAiCompany');
+    logger.newline();
 
-    // Login and get session token
-    const spin = logger.spinner('Logging in...').start();
+    // CASE 1: Login with API key (fast path)
+    if (options.apiKey) {
+      return await loginWithApiKey(email, options.apiKey);
+    }
 
-    try {
-      // Call /auth/login endpoint to get session token
-      const result = await api.login(email, apiKey);
+    // CASE 2: Verify OTP (second step)
+    if (options.otp) {
+      return await verifyOtpAndLogin(email, options.otp);
+    }
 
-      spin.succeed('Login successful!');
+    // CASE 3: Request OTP (first step)
+    return await requestOtp(email);
 
-      // Save session token and expiration
-      saveUser({
-        email: result.user.email || email,
-        userId: result.user.id,
-        sessionToken: result.session_token,
-        expiresAt: result.expires_at,
-        verified: result.user.verified,
-      });
+  } catch (error) {
+    logger.error(error.response?.data?.message || error.message);
+    process.exit(1);
+  }
+}
 
-      logger.newline();
-      logger.success('You are now logged in!');
-      logger.newline();
-      logger.field('Email', result.user.email || email);
-      logger.field('Verified', result.user.verified ? 'Yes' : 'No');
-
-      // Show expiration date
-      if (result.expires_at) {
-        const expirationDate = new Date(result.expires_at);
-        logger.field('Session expires', expirationDate.toLocaleDateString());
-      }
-
-    } catch (error) {
-      spin.fail('Login failed');
-      throw error;
+/**
+ * Login with API key (existing flow)
+ */
+async function loginWithApiKey(email, apiKey) {
+  const spin = logger.spinner('Logging in with API key...').start();
+
+  try {
+    const result = await api.login(email, apiKey);
+
+    spin.succeed('Login successful!');
+
+    // Save session token
+    saveUser({
+      email: result.user.email || email,
+      userId: result.user.id,
+      sessionToken: result.session_token,
+      expiresAt: result.expires_at,
+      verified: result.user.verified,
+    });
+
+    logger.newline();
+    logger.success('You are now logged in!');
+    logger.newline();
+    logger.field('Email', result.user.email || email);
+    logger.field('Verified', result.user.verified ? 'Yes' : 'No');
+
+    if (result.expires_at) {
+      const expirationDate = new Date(result.expires_at);
+      logger.field('Session expires', expirationDate.toLocaleDateString());
     }
+
   } catch (error) {
-    logger.error(
-      error.response?.data?.message || 'Invalid credentials'
-    );
-    process.exit(1);
+    spin.fail('Login failed');
+    throw error;
+  }
+}
+
+/**
+ * Request OTP via email (new flow - step 1)
+ */
+async function requestOtp(email) {
+  const spin = logger.spinner('Sending verification code to email...').start();
+
+  try {
+    const result = await api.requestLoginOtp(email);
+
+    spin.succeed('Verification code sent!');
+
+    logger.newline();
+    logger.success(`A verification code has been sent to ${logger.chalk.cyan(email)}`);
+    logger.newline();
+    logger.info('Check your email and run:');
+    logger.log(`  ${logger.chalk.yellow(`saac login -e ${email} --otp <code>`)}`);
+    logger.newline();
+    logger.warn('Note: Check MailHog at https://mailhog.goryan.io for the verification code');
+    logger.newline();
+
+    if (result.otp_expires_at) {
+      const expiresAt = new Date(result.otp_expires_at);
+      const now = new Date();
+      const minutesLeft = Math.ceil((expiresAt - now) / 60000);
+      logger.info(`Code expires in ${minutesLeft} minutes`);
+    }
+
+  } catch (error) {
+    spin.fail('Failed to send verification code');
+    throw error;
+  }
+}
+
+/**
+ * Verify OTP and complete login (new flow - step 2)
+ */
+async function verifyOtpAndLogin(email, otpCode) {
+  const spin = logger.spinner('Verifying code...').start();
+
+  try {
+    const result = await api.verifyLoginOtp(email, otpCode);
+
+    spin.succeed('Verification successful!');
+
+    // Save session token
+    saveUser({
+      email: result.user.email || email,
+      userId: result.user.id,
+      sessionToken: result.session_token,
+      expiresAt: result.expires_at,
+      verified: result.user.verified,
+    });
+
+    logger.newline();
+    logger.success('You are now logged in!');
+    logger.newline();
+    logger.field('Email', result.user.email || email);
+    logger.field('Verified', result.user.verified ? 'Yes' : 'No');
+
+    if (result.expires_at) {
+      const expirationDate = new Date(result.expires_at);
+      logger.field('Session expires', expirationDate.toLocaleDateString());
+    }
+
+    logger.newline();
+    logger.info('💡 Tip: Generate an API key for faster future logins:');
+    logger.log('  saac keys regenerate');
+
+  } catch (error) {
+    spin.fail('Verification failed');
+
+    if (error.response?.status === 401) {
+      logger.newline();
+      logger.error('Invalid or expired verification code');
+      logger.info('Request a new code:');
+      logger.log(`  saac login -e ${email}`);
+    }
+
+    throw error;
   }
 }
 

package/src/lib/api.js

@@ -181,6 +181,61 @@ async function healthCheck() {
   return response.data;
 }
 
+/**
+ * Request login OTP (no API key required)
+ */
+async function requestLoginOtp(email) {
+  const client = axios.create({
+    baseURL: getApiUrl(),
+    timeout: 30000,
+    headers: {
+      'Content-Type': 'application/json',
+      'User-Agent': `saac-cli/${pkg.version} (${os.platform()}; ${os.arch()})`,
+    },
+  });
+
+  const response = await client.post('/auth/login-otp', { email });
+  return response.data;
+}
+
+/**
+ * Verify login OTP and get session token
+ */
+async function verifyLoginOtp(email, otpCode) {
+  const client = axios.create({
+    baseURL: getApiUrl(),
+    timeout: 30000,
+    headers: {
+      'Content-Type': 'application/json',
+      'User-Agent': `saac-cli/${pkg.version} (${os.platform()}; ${os.arch()})`,
+    },
+  });
+
+  const response = await client.post('/auth/verify-otp', {
+    email,
+    otp_code: otpCode,
+  });
+  return response.data;
+}
+
+/**
+ * Regenerate API key (requires authentication)
+ */
+async function regenerateApiKey() {
+  const client = createClient();
+  const response = await client.post('/users/regenerate-key');
+  return response.data;
+}
+
+/**
+ * Get API key info (prefix, created date, last used)
+ */
+async function getApiKeyInfo() {
+  const client = createClient();
+  const response = await client.get('/users/api-key');
+  return response.data;
+}
+
 module.exports = {
   createClient,
   login,
@@ -197,4 +252,8 @@ module.exports = {
   updateDomain,
   deleteApplication,
   healthCheck,
+  requestLoginOtp,
+  verifyLoginOtp,
+  regenerateApiKey,
+  getApiKeyInfo,
 };