@cardstack/boxel-cli 0.2.0-unstable.425 → 0.2.0-unstable.446

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardstack/boxel-cli",
-  "version": "0.2.0-unstable.425",
+  "version": "0.2.0-unstable.446",
   "license": "MIT",
   "description": "CLI tools for Boxel workspace management",
   "main": "./dist/index.js",
@@ -54,8 +54,8 @@
     "vite": "^6.3.2",
     "vitest": "^2.1.9",
     "@cardstack/postgres": "0.0.0",
-    "@cardstack/local-types": "0.0.0",
-    "@cardstack/runtime-common": "1.0.0"
+    "@cardstack/runtime-common": "1.0.0",
+    "@cardstack/local-types": "0.0.0"
   },
   "publishConfig": {
     "access": "public",

package/src/commands/profile.ts

@@ -80,7 +80,7 @@ function validateUrl(input: string, label: string): string {
 
 // Matches scripts/env-slug.sh: lowercase, "/" -> "-", strip chars outside
 // [a-z0-9-], collapse runs of "-", trim leading/trailing "-".
-function computeEnvSlug(name: string): string {
+export function computeEnvSlug(name: string): string {
   return name
     .toLowerCase()
     .replace(/\//g, '-')
@@ -91,7 +91,7 @@ function computeEnvSlug(name: string): string {
 
 // Derive URLs from BOXEL_ENVIRONMENT using the same ".${slug}.localhost"
 // pattern that mise-tasks/lib/env-vars.sh produces for env-mode local dev.
-function resolveBoxelEnvironment(): EnvironmentDefaults | null {
+export function resolveBoxelEnvironment(): EnvironmentDefaults | null {
   const raw = process.env.BOXEL_ENVIRONMENT;
   if (!raw || !raw.trim()) return null;
   const slug = computeEnvSlug(raw);
@@ -458,14 +458,28 @@ async function addProfileNonInteractive(
     process.exit(1);
   }
 
-  if (manager.getProfile(matrixId)) {
-    console.log(
-      `${FG_YELLOW}Profile ${matrixId} already exists. Updating password.${RESET}`,
+  const isUpdate = Boolean(manager.getProfile(matrixId));
+
+  // addProfile performs a real matrixLogin and persists the resulting
+  // access token (the password never lands on disk). It also handles the
+  // create-vs-reauth split uniformly: re-running it on an existing profile
+  // refreshes the stored token while preserving cached realm tokens.
+  try {
+    await manager.addProfile(
+      matrixId,
+      password,
+      displayName,
+      matrixUrl,
+      realmServerUrl,
     );
-    await manager.updatePassword(matrixId, password);
-    if (displayName) {
-      manager.updateDisplayName(matrixId, displayName);
-    }
+  } catch (err) {
+    console.error(
+      `${FG_RED}Error:${RESET} ${err instanceof Error ? err.message : String(err)}`,
+    );
+    process.exit(1);
+  }
+
+  if (isUpdate) {
     if (matrixUrl || realmServerUrl) {
       const urlsChanged = manager.updateUrls(matrixId, {
         matrixUrl,
@@ -483,20 +497,6 @@ async function addProfileNonInteractive(
     return;
   }
 
-  try {
-    await manager.addProfile(
-      matrixId,
-      password,
-      displayName,
-      matrixUrl,
-      realmServerUrl,
-    );
-  } catch (err) {
-    console.error(
-      `${FG_RED}Error:${RESET} ${err instanceof Error ? err.message : String(err)}`,
-    );
-    process.exit(1);
-  }
   console.log(
     `${FG_GREEN}\u2713${RESET} Profile created: ${formatProfileBadge(matrixId)}`,
   );
@@ -538,7 +538,7 @@ async function migrateFromEnv(manager: ProfileManager): Promise<void> {
       );
     } else {
       console.log(
-        `${FG_YELLOW}Profile ${formatProfileBadge(result.profileId)} already exists.${RESET} Password has been updated if it changed.`,
+        `${FG_GREEN}\u2713${RESET} Refreshed profile: ${formatProfileBadge(result.profileId)}`,
       );
       console.log(
         `\n${DIM}Use 'boxel profile add -u ${result.profileId} -p <password>' to update other fields.${RESET}`,

package/src/lib/auth.ts

@@ -7,6 +7,17 @@ export interface MatrixAuth {
 
 export type RealmTokens = Record<string, string>;
 
+// Thrown when Matrix rejects an access token (401/403). Callers can catch
+// this specifically to drive interactive re-auth without parsing messages.
+export class MatrixAuthError extends Error {
+  status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = 'MatrixAuthError';
+    this.status = status;
+  }
+}
+
 interface MatrixLoginResponse {
   access_token: string;
   device_id: string;
@@ -69,6 +80,12 @@ async function getOpenIdToken(
 
   if (!response.ok) {
     let text = await response.text();
+    if (response.status === 401 || response.status === 403) {
+      throw new MatrixAuthError(
+        response.status,
+        `OpenID token request failed: ${response.status} ${text}`,
+      );
+    }
     throw new Error(`OpenID token request failed: ${response.status} ${text}`);
   }
 
@@ -138,17 +155,30 @@ function userRealmsAccountDataUrl(matrixAuth: MatrixAuth): string {
 export async function getUserRealmsFromMatrixAccountData(
   matrixAuth: MatrixAuth,
 ): Promise<string[]> {
+  let response: Response;
   try {
-    let response = await fetch(userRealmsAccountDataUrl(matrixAuth), {
+    response = await fetch(userRealmsAccountDataUrl(matrixAuth), {
       headers: { Authorization: `Bearer ${matrixAuth.accessToken}` },
     });
-    if (!response.ok) {
-      return [];
-    }
+  } catch {
+    // Network unreachable / DNS / similar — treat as empty (best-effort).
+    return [];
+  }
+  if (response.status === 401 || response.status === 403) {
+    let text = await response.text();
+    throw new MatrixAuthError(
+      response.status,
+      `Matrix account_data fetch failed: ${response.status} ${text}`,
+    );
+  }
+  if (!response.ok) {
+    // 404 just means the event has never been set — return empty list.
+    return [];
+  }
+  try {
     let data = (await response.json()) as { realms?: string[] };
     return Array.isArray(data.realms) ? [...data.realms] : [];
   } catch {
-    // Best-effort — treat unreachable account data as an empty list
     return [];
   }
 }
@@ -171,6 +201,12 @@ export async function addRealmToMatrixAccountData(
     });
     if (!putResponse.ok) {
       let text = await putResponse.text();
+      if (putResponse.status === 401 || putResponse.status === 403) {
+        throw new MatrixAuthError(
+          putResponse.status,
+          `Failed to update Matrix account data: ${putResponse.status} ${text}`,
+        );
+      }
       throw new Error(
         `Failed to update Matrix account data: ${putResponse.status} ${text}`,
       );
@@ -205,6 +241,12 @@ export async function removeRealmFromMatrixAccountData(
   });
   if (!putResponse.ok) {
     let text = await putResponse.text();
+    if (putResponse.status === 401 || putResponse.status === 403) {
+      throw new MatrixAuthError(
+        putResponse.status,
+        `Failed to update Matrix account data: ${putResponse.status} ${text}`,
+      );
+    }
     throw new Error(
       `Failed to update Matrix account data: ${putResponse.status} ${text}`,
     );

package/src/lib/profile-manager.ts

@@ -5,6 +5,7 @@ import jwt from 'jsonwebtoken';
 import { FG_YELLOW, FG_CYAN, FG_MAGENTA, DIM, BOLD, RESET } from './colors';
 import {
   matrixLogin,
+  MatrixAuthError,
   getRealmServerToken as fetchRealmServerToken,
   getRealmTokens,
   addRealmToMatrixAccountData,
@@ -12,8 +13,15 @@ import {
   getUserRealmsFromMatrixAccountData,
   type MatrixAuth,
 } from './auth';
+import { promptPassword as defaultPromptPassword } from './prompt';
 import type { RealmAuthenticator } from './realm-authenticator';
 
+export interface ProfileManagerDeps {
+  matrixLogin?: typeof matrixLogin;
+  promptPassword?: (question: string) => Promise<string>;
+  isTty?: () => boolean;
+}
+
 const DEFAULT_CONFIG_DIR = path.join(os.homedir(), '.boxel-cli');
 const PROFILES_FILENAME = 'profiles.json';
 
@@ -49,7 +57,9 @@ export interface Profile {
   displayName: string;
   matrixUrl: string;
   realmServerUrl: string;
-  password: string; // Stored in plaintext - file should have restricted permissions, this will be updated in CS-10642
+  matrixAccessToken: string;
+  matrixUserId: string;
+  matrixDeviceId: string;
   realmTokens?: Record<string, string>;
   realmServerToken?: string;
 }
@@ -121,11 +131,17 @@ export class ProfileManager implements RealmAuthenticator {
   private config: ProfilesConfig;
   private configDir: string;
   private profilesFile: string;
+  private matrixLoginFn: typeof matrixLogin;
+  private promptPasswordFn: (question: string) => Promise<string>;
+  private isTtyFn: () => boolean;
 
-  constructor(configDir?: string) {
+  constructor(configDir?: string, deps?: ProfileManagerDeps) {
     this.configDir = configDir || DEFAULT_CONFIG_DIR;
     this.profilesFile = path.join(this.configDir, PROFILES_FILENAME);
     this.config = this.loadConfig();
+    this.matrixLoginFn = deps?.matrixLogin ?? matrixLogin;
+    this.promptPasswordFn = deps?.promptPassword ?? defaultPromptPassword;
+    this.isTtyFn = deps?.isTty ?? (() => Boolean(process.stdin.isTTY));
   }
 
   private ensureConfigDir(): void {
@@ -199,13 +215,20 @@ export class ProfileManager implements RealmAuthenticator {
     return { id, profile };
   }
 
-  async addProfile(
+  // Resolve {matrixUrl, realmServerUrl, displayName} from environment defaults
+  // and caller-provided overrides. Shared by `addProfile` and
+  // `addProfileWithAuth` so both paths agree on naming + URL inference.
+  private resolveProfileSlots(
     matrixId: string,
-    password: string,
-    displayName?: string,
-    matrixUrl?: string,
-    realmServerUrl?: string,
-  ): Promise<void> {
+    displayName: string | undefined,
+    matrixUrl: string | undefined,
+    realmServerUrl: string | undefined,
+  ): {
+    matrixUrl: string;
+    realmServerUrl: string;
+    displayName: string;
+    username: string;
+  } {
     const env = getEnvironmentFromMatrixId(matrixId);
     const username = getUsernameFromMatrixId(matrixId);
 
@@ -215,21 +238,62 @@ export class ProfileManager implements RealmAuthenticator {
       );
     }
 
-    const defaultMatrixUrl =
-      env === 'production'
-        ? 'https://matrix.boxel.ai'
-        : 'https://matrix-staging.stack.cards';
-    const defaultRealmUrl =
-      env === 'production'
-        ? 'https://app.boxel.ai/'
-        : 'https://realms-staging.stack.cards/';
+    let defaultMatrixUrl: string;
+    let defaultRealmUrl: string;
+    if (env === 'production') {
+      defaultMatrixUrl = 'https://matrix.boxel.ai';
+      defaultRealmUrl = 'https://app.boxel.ai/';
+    } else if (env === 'local') {
+      defaultMatrixUrl = 'http://localhost:8008';
+      defaultRealmUrl = 'http://localhost:4201/';
+    } else {
+      defaultMatrixUrl = 'https://matrix-staging.stack.cards';
+      defaultRealmUrl = 'https://realms-staging.stack.cards/';
+    }
 
     const domain = getDomainFromMatrixId(matrixId);
-    const profile: Profile = {
-      displayName: displayName || `${username} \u00b7 ${domain}`,
+    return {
       matrixUrl: matrixUrl || defaultMatrixUrl,
       realmServerUrl: realmServerUrl || defaultRealmUrl,
-      password,
+      displayName: displayName || `${username} \u00b7 ${domain}`,
+      username,
+    };
+  }
+
+  // Persist a profile from an already-acquired MatrixAuth. The token is
+  // stored; the original password (if any) never reaches this function. Used
+  // directly by tests, and as the "store" half of `addProfile`.
+  // When re-authing an existing profile we keep its cached realm tokens \u2014 a
+  // fresh access token doesn't invalidate the realm-server JWT. But if the
+  // matrix or realm-server URL changed, the cached tokens were minted against
+  // the old servers and must be dropped.
+  async addProfileWithAuth(
+    matrixId: string,
+    auth: MatrixAuth,
+    displayName?: string,
+    realmServerUrl?: string,
+  ): Promise<void> {
+    const slots = this.resolveProfileSlots(
+      matrixId,
+      displayName,
+      auth.matrixUrl,
+      realmServerUrl,
+    );
+
+    const existing = this.config.profiles[matrixId];
+    const urlsChanged =
+      !!existing &&
+      (existing.matrixUrl !== slots.matrixUrl ||
+        existing.realmServerUrl !== slots.realmServerUrl);
+    const profile: Profile = {
+      displayName: slots.displayName,
+      matrixUrl: slots.matrixUrl,
+      realmServerUrl: slots.realmServerUrl,
+      matrixAccessToken: auth.accessToken,
+      matrixUserId: auth.userId,
+      matrixDeviceId: auth.deviceId,
+      realmTokens: urlsChanged ? undefined : existing?.realmTokens,
+      realmServerToken: urlsChanged ? undefined : existing?.realmServerToken,
     };
 
     this.config.profiles[matrixId] = profile;
@@ -241,6 +305,44 @@ export class ProfileManager implements RealmAuthenticator {
     this.saveConfig();
   }
 
+  async addProfile(
+    matrixId: string,
+    password: string,
+    displayName?: string,
+    matrixUrl?: string,
+    realmServerUrl?: string,
+  ): Promise<void> {
+    // On re-auth, default omitted args to the existing profile's stored
+    // values so we don't silently reset display name or URLs to defaults.
+    const existing = this.config.profiles[matrixId];
+    const slots = this.resolveProfileSlots(
+      matrixId,
+      displayName ?? existing?.displayName,
+      matrixUrl ?? existing?.matrixUrl,
+      realmServerUrl ?? existing?.realmServerUrl,
+    );
+
+    const auth = await this.matrixLoginFn(
+      slots.matrixUrl,
+      slots.username,
+      password,
+    );
+
+    if (auth.userId !== matrixId) {
+      throw new Error(
+        `Matrix returned userId "${auth.userId}" but profile was added as "${matrixId}". ` +
+          `Check the Matrix ID and try again.`,
+      );
+    }
+
+    await this.addProfileWithAuth(
+      matrixId,
+      auth,
+      slots.displayName,
+      slots.realmServerUrl,
+    );
+  }
+
   async removeProfile(profileId: string): Promise<boolean> {
     if (!this.config.profiles[profileId]) {
       return false;
@@ -266,56 +368,6 @@ export class ProfileManager implements RealmAuthenticator {
     return true;
   }
 
-  async getActiveCredentials(): Promise<{
-    matrixUrl: string;
-    username: string;
-    password: string;
-    realmServerUrl: string;
-    profileId: string | null;
-  } | null> {
-    const active = this.getActiveProfile();
-    if (active && active.profile.password) {
-      return {
-        matrixUrl: active.profile.matrixUrl,
-        username: getUsernameFromMatrixId(active.id),
-        password: active.profile.password,
-        realmServerUrl: active.profile.realmServerUrl,
-        profileId: active.id,
-      };
-    }
-
-    const matrixUrl = process.env.MATRIX_URL;
-    const username = process.env.MATRIX_USERNAME;
-    const password = process.env.MATRIX_PASSWORD;
-    const realmServerUrl = process.env.REALM_SERVER_URL;
-
-    if (matrixUrl && username && password && realmServerUrl) {
-      return {
-        matrixUrl,
-        username,
-        password,
-        realmServerUrl,
-        profileId: null,
-      };
-    }
-
-    return null;
-  }
-
-  async getPassword(profileId: string): Promise<string | null> {
-    const profile = this.config.profiles[profileId];
-    return profile?.password || null;
-  }
-
-  async updatePassword(profileId: string, password: string): Promise<boolean> {
-    if (!this.config.profiles[profileId]) {
-      return false;
-    }
-    this.config.profiles[profileId].password = password;
-    this.saveConfig();
-    return true;
-  }
-
   updateDisplayName(profileId: string, displayName: string): boolean {
     if (!this.config.profiles[profileId]) {
       return false;
@@ -385,14 +437,92 @@ export class ProfileManager implements RealmAuthenticator {
     return active?.profile.realmServerToken;
   }
 
-  private async loginToMatrix(): Promise<MatrixAuth> {
-    let active = this.getActiveProfile();
-    if (!active) {
-      throw new Error('No active profile');
+  // Return the Matrix credentials stored for a profile. Sync — reads only
+  // the in-memory `this.config`, which is populated by the constructor.
+  // Throws when the profile has no stored token yet (e.g. a pre-CS-10725
+  // profile still on disk from before the password→token swap).
+  getStoredMatrixAuth(profileId?: string): MatrixAuth {
+    const targetId = profileId ?? this.config.activeProfile ?? undefined;
+    const profile = targetId ? this.config.profiles[targetId] : undefined;
+    if (!targetId || !profile) {
+      throw new Error(NO_ACTIVE_PROFILE_ERROR);
+    }
+    if (!profile.matrixAccessToken) {
+      throw new Error(
+        `Profile "${targetId}" has no stored Matrix access token. ` +
+          `Run \`boxel profile add\` to re-authenticate.`,
+      );
+    }
+    return {
+      accessToken: profile.matrixAccessToken,
+      userId: profile.matrixUserId,
+      deviceId: profile.matrixDeviceId,
+      matrixUrl: profile.matrixUrl,
+    };
+  }
+
+  // When the stored access token gets rejected by Matrix (revoked, expired,
+  // server-side device deletion), prompt the user for their password on a
+  // TTY, run matrixLogin again, persist the new tokens, and return the
+  // refreshed MatrixAuth. Non-TTY contexts get a clear "re-add the profile"
+  // error instead of hanging on a prompt that can never be answered.
+  async reAuthenticate(profileId?: string): Promise<MatrixAuth> {
+    const targetId = profileId ?? this.config.activeProfile ?? undefined;
+    const profile = targetId ? this.config.profiles[targetId] : undefined;
+    if (!targetId || !profile) {
+      throw new Error(NO_ACTIVE_PROFILE_ERROR);
+    }
+
+    if (!this.isTtyFn()) {
+      throw new Error(
+        `Stored Matrix token for "${targetId}" is no longer valid. ` +
+          `Run \`boxel profile add -u ${targetId} -p <password>\` to re-authenticate.`,
+      );
+    }
+
+    console.log(
+      `\n${FG_YELLOW}Stored Matrix session for ${formatProfileBadge(targetId)} has expired.${RESET}`,
+    );
+    const password = await this.promptPasswordFn(`Password for ${targetId}: `);
+    if (!password) {
+      throw new Error('Re-authentication cancelled: password is required.');
+    }
+
+    const username = getUsernameFromMatrixId(targetId);
+    const auth = await this.matrixLoginFn(
+      profile.matrixUrl,
+      username,
+      password,
+    );
+    await this.addProfileWithAuth(
+      targetId,
+      auth,
+      profile.displayName,
+      profile.realmServerUrl,
+    );
+    return this.getStoredMatrixAuth(targetId);
+  }
+
+  // Wrap a realm-server-token fetch in the standard "if Matrix says 401,
+  // re-auth and retry once" recovery. Centralised so getOrRefreshServerToken
+  // and refreshServerToken share the same behaviour.
+  private async fetchRealmServerTokenWithReauth(): Promise<string> {
+    const matrixAuth = this.getStoredMatrixAuth();
+    const active = this.getActiveProfile()!;
+    const realmServerUrl = active.profile.realmServerUrl.replace(/\/$/, '');
+    try {
+      const token = await fetchRealmServerToken(matrixAuth, realmServerUrl);
+      this.setRealmServerToken(token);
+      return token;
+    } catch (e) {
+      if (!(e instanceof MatrixAuthError)) {
+        throw e;
+      }
+      const freshAuth = await this.reAuthenticate();
+      const token = await fetchRealmServerToken(freshAuth, realmServerUrl);
+      this.setRealmServerToken(token);
+      return token;
     }
-    let { id, profile } = active;
-    let username = getUsernameFromMatrixId(id);
-    return matrixLogin(profile.matrixUrl, username, profile.password);
   }
 
   async getOrRefreshServerToken(): Promise<string> {
@@ -400,21 +530,11 @@ export class ProfileManager implements RealmAuthenticator {
     if (cached && !isJwtNearExpiry(cached)) {
       return cached;
     }
-    let matrixAuth = await this.loginToMatrix();
-    let active = this.getActiveProfile()!;
-    let realmServerUrl = active.profile.realmServerUrl.replace(/\/$/, '');
-    let token = await fetchRealmServerToken(matrixAuth, realmServerUrl);
-    this.setRealmServerToken(token);
-    return token;
+    return this.fetchRealmServerTokenWithReauth();
   }
 
   async refreshServerToken(): Promise<string> {
-    let matrixAuth = await this.loginToMatrix();
-    let active = this.getActiveProfile()!;
-    let realmServerUrl = active.profile.realmServerUrl.replace(/\/$/, '');
-    let token = await fetchRealmServerToken(matrixAuth, realmServerUrl);
-    this.setRealmServerToken(token);
-    return token;
+    return this.fetchRealmServerTokenWithReauth();
   }
 
   private findRealmTokenForUrl(url: string): string | undefined {
@@ -546,19 +666,38 @@ export class ProfileManager implements RealmAuthenticator {
     return token;
   }
 
+  // Run a Matrix call that uses the stored access token, falling back to
+  // interactive re-auth + retry on a 401 (revoked / expired token).
+  private async withMatrixAuthRecovery<T>(
+    fn: (matrixAuth: MatrixAuth) => Promise<T>,
+  ): Promise<T> {
+    try {
+      return await fn(this.getStoredMatrixAuth());
+    } catch (e) {
+      if (!(e instanceof MatrixAuthError)) {
+        throw e;
+      }
+      const freshAuth = await this.reAuthenticate();
+      return fn(freshAuth);
+    }
+  }
+
   async addToUserRealms(realmUrl: string): Promise<void> {
-    let matrixAuth = await this.loginToMatrix();
-    await addRealmToMatrixAccountData(matrixAuth, realmUrl);
+    await this.withMatrixAuthRecovery((auth) =>
+      addRealmToMatrixAccountData(auth, realmUrl),
+    );
   }
 
   async removeFromUserRealms(realmUrl: string): Promise<boolean> {
-    let matrixAuth = await this.loginToMatrix();
-    return removeRealmFromMatrixAccountData(matrixAuth, realmUrl);
+    return this.withMatrixAuthRecovery((auth) =>
+      removeRealmFromMatrixAccountData(auth, realmUrl),
+    );
   }
 
   async getUserRealms(): Promise<string[]> {
-    let matrixAuth = await this.loginToMatrix();
-    return getUserRealmsFromMatrixAccountData(matrixAuth);
+    return this.withMatrixAuthRecovery((auth) =>
+      getUserRealmsFromMatrixAccountData(auth),
+    );
   }
 
   async migrateFromEnv(): Promise<{
@@ -578,15 +717,7 @@ export class ProfileManager implements RealmAuthenticator {
     const domain = isProduction ? 'boxel.ai' : 'stack.cards';
     const matrixId = `@${username}:${domain}`;
 
-    if (this.config.profiles[matrixId]) {
-      // Update password if it changed
-      if (this.config.profiles[matrixId].password !== password) {
-        this.config.profiles[matrixId].password = password;
-        this.saveConfig();
-      }
-      return { profileId: matrixId, created: false };
-    }
-
+    const created = !this.config.profiles[matrixId];
     await this.addProfile(
       matrixId,
       password,
@@ -594,7 +725,7 @@ export class ProfileManager implements RealmAuthenticator {
       matrixUrl,
       realmServerUrl,
     );
-    return { profileId: matrixId, created: true };
+    return { profileId: matrixId, created };
   }
 
   printStatus(): void {
@@ -610,11 +741,6 @@ export class ProfileManager implements RealmAuthenticator {
       console.log(
         `  ${DIM}Realm Server:${RESET} ${active.profile.realmServerUrl}`,
       );
-    } else if (process.env.MATRIX_USERNAME) {
-      console.log(
-        `\n${BOLD}Using environment variables${RESET} (no profile active)`,
-      );
-      console.log(`  ${DIM}Username:${RESET} ${process.env.MATRIX_USERNAME}`);
     } else {
       console.log(
         `\n${FG_YELLOW}No active profile and no environment variables set.${RESET}`,