teleportation-cli 1.1.4 → 1.2.0

package/.claude/hooks/user_prompt_submit.mjs

@@ -46,6 +46,10 @@ const fetchJson = async (url, opts) => {
 
   const { session_id, prompt } = input;
 
+  // Detect message source
+  const isAutonomousTask = env.TELEPORTATION_TASK_MODE === 'true' || !!env.TELEPORTATION_PARENT_SESSION_ID;
+  const source = isAutonomousTask ? 'autonomous_task' : 'cli_interactive';
+
   // Clear away mode only on actual user activity (prompt submit), not on tool attempts.
   // Also support /away and /back here in case they are handled as prompts.
   if (session_id && prompt && typeof prompt === 'string') {
@@ -53,8 +57,15 @@ const fetchJson = async (url, opts) => {
     const lowered = trimmed.toLowerCase();
 
     let desiredAway = null;
-    if (lowered === '/away' || lowered === 'teleportation away') desiredAway = true;
-    else if (lowered === '/back' || lowered === 'teleportation back') desiredAway = false;
+    // Support multiple command formats: /away, teleportation away, teleport away, teleporation away (typo)
+    if (lowered === '/away' ||
+        lowered === 'teleportation away' ||
+        lowered === 'teleport away' ||
+        lowered === 'teleporation away') desiredAway = true;
+    else if (lowered === '/back' ||
+             lowered === 'teleportation back' ||
+             lowered === 'teleport back' ||
+             lowered === 'teleporation back') desiredAway = false;
     else if (trimmed.length > 0) desiredAway = false;
 
     if (desiredAway !== null) {
@@ -66,13 +77,21 @@ const fetchJson = async (url, opts) => {
         const RELAY_API_KEY = env.RELAY_API_KEY || config.relayApiKey || '';
 
         if (RELAY_API_URL && RELAY_API_KEY) {
+          // When user types locally, signal they're back and set location to 'local'
+          // This helps the daemon know to stop auto-continuing after approvals
+          const patchBody = { is_away: desiredAway };
+          if (desiredAway === false) {
+            // User is active locally - mark location as 'local'
+            patchBody.last_approval_location = 'local';
+          }
+
           await fetchJson(`${RELAY_API_URL}/api/sessions/${session_id}/daemon-state`, {
             method: 'PATCH',
             headers: {
               'Content-Type': 'application/json',
               'Authorization': `Bearer ${RELAY_API_KEY}`
             },
-            body: JSON.stringify({ is_away: desiredAway })
+            body: JSON.stringify(patchBody)
           });
           
           // Log away_mode_changed event to timeline (only for explicit /away or /back commands)
@@ -89,6 +108,7 @@ const fetchJson = async (url, opts) => {
                 body: JSON.stringify({
                   session_id,
                   type: 'away_mode_changed',
+                  source,
                   data: {
                     is_away: desiredAway,
                     source: 'user_prompt',
@@ -150,6 +170,7 @@ const fetchJson = async (url, opts) => {
             body: JSON.stringify({
               session_id,
               type: 'model_change_requested',
+              source,
               data: {
                 command: prompt,
                 timestamp: Date.now()
@@ -200,10 +221,12 @@ const fetchJson = async (url, opts) => {
             body: JSON.stringify({
               session_id,
               type: 'user_message',
+              source,
               data: {
                 prompt: truncatedPrompt,
                 full_length: trimmed.length,
                 truncated: trimmed.length > MAX_PROMPT_LENGTH,
+                source: 'cli',
                 timestamp: Date.now()
               }
             })

package/README.md

@@ -199,6 +199,13 @@ Configuration is stored in `~/.teleportation/`:
     └── teleportation     # CLI symlink
 ```
 
+## Documentation
+
+- `RUNBOOK.md` - What must be running (local/prod) + smoke checks
+- `docs/E2E_TEST_PLAN.md` - End-to-end test plan and minimum regression matrix
+- `DEPLOYMENT_GUIDE.md` - Fly.io / Cloudflare deployment steps
+- `CHANGELOG.md` - Versioned change history
+
 Environment variables:
 - `TELEPORTATION_RELAY_URL` - Custom relay server URL
 - `TELEPORTATION_API_KEY` - API key for authentication

package/lib/auth/api-key.js

@@ -70,6 +70,18 @@ export async function testApiKey(apiKey, relayApiUrl, retryOptions = {}) {
       return { valid: true, data };
     } else if (response.status === 401) {
       return { valid: false, error: 'Invalid API key - authentication failed. Please check your API key and try again.' };
+    } else if (response.status === 403) {
+      // PRD-0018: Handle orphan API keys
+      const data = await response.json().catch(() => ({}));
+      if (data.error === 'orphan_api_key') {
+        return { 
+          valid: false, 
+          error: 'Orphan API key - not linked to an account.', 
+          isOrphan: true,
+          message: data.message 
+        };
+      }
+      return { valid: false, error: `Forbidden: ${data.message || 'You do not have permission to access this resource.'}` };
     } else if (response.status >= 500) {
       return { valid: false, error: `Relay API server error (${response.status}). The server may be temporarily unavailable. Please try again later.` };
     } else {

package/lib/auth/token-refresh.js

@@ -0,0 +1,286 @@
+/**
+ * JWT Token Auto-Refresh Module (PRD-0019)
+ *
+ * Provides automatic access token refresh functionality for CLI and hooks.
+ * Access tokens are short-lived (15 min default), this module handles
+ * transparent refresh using the stored refresh token.
+ */
+
+import { CredentialManager } from './credentials.js';
+
+// Refresh access token if it expires within this time (ms)
+const REFRESH_BUFFER_MS = 60000; // 1 minute before expiry
+
+// Timeout for refresh API calls (ms)
+const REFRESH_TIMEOUT_MS = 10000; // 10 seconds
+
+// Retry on 401 (handles race condition when multiple hooks refresh concurrently)
+const MAX_REFRESH_RETRIES = 1;
+
+// Valid range for expiresIn (seconds) - prevents malicious/buggy server values
+const MIN_EXPIRES_IN = 60; // 1 minute minimum
+const MAX_EXPIRES_IN = 86400; // 24 hours maximum
+const DEFAULT_EXPIRES_IN = 900; // 15 minutes default
+
+/**
+ * Get a valid access token, refreshing if necessary.
+ *
+ * This is the main function used by hooks and CLI to get an authentication token.
+ * It handles:
+ * 1. Loading credentials from encrypted storage
+ * 2. Checking if access token is still valid
+ * 3. Refreshing the token if expired or expiring soon
+ * 4. Updating stored credentials with new tokens
+ *
+ * @param {object} options - Optional configuration
+ * @param {string} options.credentialsPath - Custom credentials path (for testing)
+ * @param {string} options.keyPath - Custom key path (for testing)
+ * @returns {Promise<string>} Valid access token
+ * @throws {Error} If no credentials, refresh fails, or session expired
+ *
+ * @example
+ * ```javascript
+ * import { getValidAccessToken } from './token-refresh.js';
+ *
+ * const token = await getValidAccessToken();
+ * const response = await fetch(url, {
+ *   headers: { Authorization: `Bearer ${token}` }
+ * });
+ * ```
+ */
+export async function getValidAccessToken(options = {}) {
+  const manager = new CredentialManager(options.credentialsPath, options.keyPath);
+
+  // Load current credentials (use let to allow reassignment on retry)
+  let credentials = await manager.load();
+
+  if (!credentials) {
+    throw new Error('No credentials found. Run: teleportation login');
+  }
+
+  // Check for JWT credentials
+  if (!credentials.refreshToken) {
+    // Fall back to legacy API key if available
+    if (credentials.apiKey) {
+      return credentials.apiKey;
+    }
+    throw new Error('No JWT or API key found. Run: teleportation login');
+  }
+
+  // Check if access token is still valid
+  const now = Date.now();
+  const expiresAt = credentials.accessTokenExpiresAt || 0;
+  const needsRefresh = expiresAt < (now + REFRESH_BUFFER_MS);
+
+  if (!needsRefresh && credentials.accessToken) {
+    // Access token is still valid
+    return credentials.accessToken;
+  }
+
+  // Need to refresh - call the relay API
+  const relayUrl = credentials.relayApiUrl || 'https://api.teleportation.dev';
+
+  // Retry loop handles race condition when multiple hooks refresh concurrently
+  // (one hook rotates the refresh token, making the other's token invalid)
+  let lastError = null;
+  for (let attempt = 0; attempt <= MAX_REFRESH_RETRIES; attempt++) {
+    try {
+      // Reload credentials on retry (another process may have updated them)
+      if (attempt > 0) {
+        const freshCredentials = await manager.load();
+        if (freshCredentials && freshCredentials.refreshToken) {
+          credentials = freshCredentials;
+          // Check if fresh credentials have a valid access token
+          const freshExpiresAt = freshCredentials.accessTokenExpiresAt || 0;
+          if (freshExpiresAt > (Date.now() + REFRESH_BUFFER_MS) && freshCredentials.accessToken) {
+            // Another process already refreshed, use the new token
+            // Debug: race condition resolved by using fresh credentials
+            if (process.env.DEBUG) {
+              console.error('[token-refresh] Race condition resolved: using token refreshed by another process');
+            }
+            return freshCredentials.accessToken;
+          }
+        }
+      }
+
+      // Create abort controller for timeout
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), REFRESH_TIMEOUT_MS);
+
+      let response;
+      try {
+        response = await fetch(`${relayUrl}/api/auth/refresh`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({ refreshToken: credentials.refreshToken }),
+          signal: controller.signal,
+        });
+      } finally {
+        clearTimeout(timeoutId);
+      }
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+
+        if (response.status === 401) {
+          // Refresh token is invalid - could be race condition, retry once
+          if (attempt < MAX_REFRESH_RETRIES) {
+            lastError = new Error('Refresh token invalid, retrying...');
+            continue; // Retry with fresh credentials
+          }
+          // Final attempt failed
+          throw new Error(
+            'Session expired. Run: teleportation login\n' +
+            'Your refresh token is no longer valid.'
+          );
+        }
+
+        if (response.status === 503) {
+          throw new Error(
+            'JWT authentication is not enabled on this relay.\n' +
+            'Use API key authentication: teleportation login --api-key YOUR_KEY'
+          );
+        }
+
+        throw new Error(
+          `Failed to refresh token: ${errorData.message || response.statusText}`
+        );
+      }
+
+      const tokenData = await response.json();
+
+      // Validate required fields in response
+      if (!tokenData.accessToken || !tokenData.refreshToken) {
+        throw new Error(
+          'Invalid token response from relay: missing accessToken or refreshToken'
+        );
+      }
+
+      // Validate and clamp expiresIn to prevent malicious/buggy server values
+      let expiresIn = DEFAULT_EXPIRES_IN;
+      if (typeof tokenData.expiresIn === 'number') {
+        // Clamp to valid range (1 minute to 24 hours)
+        expiresIn = Math.max(MIN_EXPIRES_IN, Math.min(MAX_EXPIRES_IN, tokenData.expiresIn));
+        if (expiresIn !== tokenData.expiresIn && process.env.DEBUG) {
+          console.error(`[token-refresh] expiresIn clamped from ${tokenData.expiresIn}s to ${expiresIn}s`);
+        }
+      }
+
+      // Calculate new expiry time
+      const newExpiresAt = Date.now() + (expiresIn * 1000);
+
+      // Update stored credentials
+      await manager.update({
+        accessToken: tokenData.accessToken,
+        refreshToken: tokenData.refreshToken, // Refresh token is rotated
+        accessTokenExpiresAt: newExpiresAt,
+        refreshTokenId: tokenData.refreshTokenId,
+      });
+
+      return tokenData.accessToken;
+    } catch (error) {
+      // Handle abort (timeout)
+      if (error.name === 'AbortError') {
+        throw new Error(
+          `Token refresh timed out after ${REFRESH_TIMEOUT_MS / 1000} seconds.\n` +
+          'Check your network connection or relay URL.'
+        );
+      }
+
+      // Handle network errors
+      if (error.message.includes('fetch failed') || error.code === 'ECONNREFUSED') {
+        throw new Error(
+          `Cannot reach relay at ${relayUrl}.\n` +
+          'Check your network connection or relay URL.'
+        );
+      }
+
+      lastError = error;
+
+      // Don't retry on non-401 errors
+      if (!error.message.includes('retrying')) {
+        throw error;
+      }
+    }
+  }
+
+  // If we get here, all retries failed
+  throw lastError || new Error('Token refresh failed after retries');
+}
+
+/**
+ * Check if credentials have a valid JWT configuration.
+ *
+ * @param {object} options - Optional configuration
+ * @param {string} options.credentialsPath - Custom credentials path
+ * @param {string} options.keyPath - Custom key path
+ * @returns {Promise<boolean>} True if JWT credentials are present
+ */
+export async function hasJwtCredentials(options = {}) {
+  try {
+    const manager = new CredentialManager(options.credentialsPath, options.keyPath);
+    const credentials = await manager.load();
+    return !!(credentials && credentials.refreshToken);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if credentials have any valid authentication method.
+ *
+ * @param {object} options - Optional configuration
+ * @returns {Promise<{hasJwt: boolean, hasApiKey: boolean, method: string|null}>}
+ */
+export async function getAuthMethod(options = {}) {
+  try {
+    const manager = new CredentialManager(options.credentialsPath, options.keyPath);
+    const credentials = await manager.load();
+
+    if (!credentials) {
+      return { hasJwt: false, hasApiKey: false, method: null };
+    }
+
+    const hasJwt = !!credentials.refreshToken;
+    const hasApiKey = !!credentials.apiKey;
+
+    let method = null;
+    if (hasJwt) {
+      method = 'jwt';
+    } else if (hasApiKey) {
+      method = 'api-key';
+    }
+
+    return { hasJwt, hasApiKey, method };
+  } catch {
+    return { hasJwt: false, hasApiKey: false, method: null };
+  }
+}
+
+/**
+ * Get token expiry information.
+ *
+ * @param {object} options - Optional configuration
+ * @returns {Promise<{expiresAt: number|null, expiresIn: number|null, isExpired: boolean}>}
+ */
+export async function getTokenExpiry(options = {}) {
+  try {
+    const manager = new CredentialManager(options.credentialsPath, options.keyPath);
+    const credentials = await manager.load();
+
+    if (!credentials || !credentials.accessTokenExpiresAt) {
+      return { expiresAt: null, expiresIn: null, isExpired: true };
+    }
+
+    const now = Date.now();
+    const expiresAt = credentials.accessTokenExpiresAt;
+    const expiresIn = Math.max(0, expiresAt - now);
+    const isExpired = expiresAt < now;
+
+    return { expiresAt, expiresIn, isExpired };
+  } catch {
+    return { expiresAt: null, expiresIn: null, isExpired: true };
+  }
+}

package/lib/cli/daemon-commands.js

@@ -3,7 +3,7 @@
  * Handles away mode, back mode, and daemon status commands
  */
 
-import { checkDaemonStatus, startDaemon, stopDaemon } from '../daemon/pid-manager.js';
+import { checkDaemonStatus, startDaemon, stopDaemon } from '../daemon/lifecycle.js';
 
 // Color helpers
 const c = {