spaps 0.7.3 → 0.7.5

package/src/auth/env.js

@@ -0,0 +1,57 @@
+// Environment detection for the SPAPS CLI auth flow.
+//
+// Determines whether we're in a headless context (SSH, no GUI) so the login
+// command can print the verification URL for copy-paste instead of trying to
+// open a browser that isn't there.
+//
+// TODO(tier1/tier2): when the backend exposes loopback-PKCE routes, use this to
+// pick Tier 1 (browser PKCE) on local GUI and Tier 2 (manual paste PKCE) on
+// SSH, keeping Tier 3 (device code) as the fallback.
+
+const { spawn } = require('node:child_process');
+
+function isSsh(env = process.env) {
+  return Boolean(env.SSH_CLIENT || env.SSH_TTY || env.SSH_CONNECTION);
+}
+
+function hasGui(env = process.env, platform = process.platform) {
+  if (platform === 'darwin' || platform === 'win32') return true;
+  return Boolean(env.DISPLAY || env.WAYLAND_DISPLAY);
+}
+
+function isHeadless(env = process.env, platform = process.platform) {
+  return isSsh(env) || !hasGui(env, platform);
+}
+
+function tryOpenBrowser(url, { env = process.env, platform = process.platform } = {}) {
+  if (isHeadless(env, platform)) return false;
+  try {
+    let cmd;
+    let args;
+    if (platform === 'darwin') {
+      cmd = 'open';
+      args = [url];
+    } else if (platform === 'win32') {
+      // `start` is a cmd.exe builtin; the empty title "" is required when the
+      // first quoted arg would otherwise be treated as the window title.
+      cmd = 'cmd';
+      args = ['/c', 'start', '""', url];
+    } else {
+      cmd = 'xdg-open';
+      args = [url];
+    }
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  isSsh,
+  hasGui,
+  isHeadless,
+  tryOpenBrowser,
+};

package/src/auth/handlers.js

@@ -0,0 +1,462 @@
+// Command handlers for `spaps login`, `spaps logout`, `spaps whoami`,
+// `spaps token`. Wired into the top-level handler map in src/handlers.js.
+//
+// Login uses RFC 8628 device flow (Tier 3). Tiers 1 (browser PKCE loopback)
+// and 2 (manual paste PKCE) are deferred until the SPAPS backend exposes the
+// `/auth/cli-login` / `/auth/callback` / `/auth/token` routes.
+
+const chalk = require('chalk');
+
+const {
+  startDeviceAuthorization,
+  pollForToken,
+  DeviceFlowError,
+} = require('./device-flow');
+const {
+  getCredentials,
+  setCredentials,
+  clearCredentials,
+  CREDENTIALS_PATH,
+} = require('./credentials');
+const { isHeadless, tryOpenBrowser } = require('./env');
+const { authFetch, resolveServerUrl, refreshAccessToken } = require('./client');
+const { resolveLoginClientId } = require('./client-id');
+
+function emitJsonError(command, err, extra = {}) {
+  console.log(
+    JSON.stringify(
+      {
+        success: false,
+        command,
+        error: {
+          code: err.code || 'ERROR',
+          message: err.message || String(err),
+        },
+        ...extra,
+      },
+      null,
+      2
+    )
+  );
+}
+
+async function loginHandler({ options }) {
+  const isJson = Boolean(options.json);
+  const serverUrl = resolveServerUrl(options);
+  const clientIdResult = await resolveLoginClientId({ options, serverUrl });
+  const clientId = clientIdResult.clientId;
+
+  if (!clientId) {
+    const err = new Error(
+      'Could not resolve a SPAPS application slug for device login. Pass --client-id <app-slug>, set SPAPS_CLI_CLIENT_ID, or run this command inside a repo with spaps.app.json / .spaps/app.json.'
+    );
+    err.code = 'CLIENT_ID_REQUIRED';
+    if (isJson) {
+      emitJsonError('login', err, { server_url: serverUrl });
+    } else {
+      console.error(chalk.red(`\n❌ ${err.message}`));
+    }
+    process.exit(2);
+  }
+
+  if (!isJson) {
+    console.log(chalk.gray(`Requesting device code from ${serverUrl}...`));
+    if (clientIdResult.source) {
+      const from = clientIdResult.path
+        ? `${clientIdResult.source} (${clientIdResult.path})`
+        : clientIdResult.source;
+      console.log(chalk.gray(`Using client id ${chalk.cyan(clientId)} from ${from}`));
+    }
+  }
+
+  let authResult;
+  try {
+    authResult = await startDeviceAuthorization({ serverUrl, clientId });
+  } catch (err) {
+    if (isJson) {
+      emitJsonError('login', err, { server_url: serverUrl });
+    } else {
+      console.error(chalk.red(`\n❌ ${err.message}`));
+      if (err.code === 'network_error') {
+        console.error(
+          chalk.gray(`   Is a SPAPS server running at ${serverUrl}?`)
+        );
+        console.error(
+          chalk.gray(`   Try: npx spaps local   (or set SPAPS_API_URL)`)
+        );
+      }
+    }
+    process.exit(1);
+  }
+
+  const verificationUri =
+    authResult.verification_uri_complete ||
+    authResult.verification_uri ||
+    authResult.auth_url;
+
+  if (!isJson) {
+    console.log();
+    console.log(chalk.bold('To finish signing in:'));
+    console.log();
+    console.log(`  1. Visit: ${chalk.cyan(verificationUri)}`);
+    if (authResult.user_code) {
+      console.log(`  2. Confirm code: ${chalk.bold.yellow(authResult.user_code)}`);
+    }
+    console.log();
+
+    if (isHeadless()) {
+      console.log(
+        chalk.gray(
+          '(Headless session detected — open the URL on another device)'
+        )
+      );
+    } else if (tryOpenBrowser(verificationUri)) {
+      console.log(chalk.gray('(Opened browser automatically)'));
+    } else {
+      console.log(
+        chalk.gray('(Could not auto-open a browser — visit the URL manually)')
+      );
+    }
+    console.log();
+    console.log(chalk.gray('Waiting for approval...'));
+  }
+
+  let tokenPayload;
+  try {
+    tokenPayload = await pollForToken({
+      serverUrl,
+      deviceCode: authResult.device_code,
+      clientId,
+      interval: authResult.interval,
+      expiresIn: authResult.expires_in,
+      onTick: (tick) => {
+        if (!isJson && tick.status === 'slow_down') {
+          console.log(
+            chalk.gray(`  (server requested slow down — interval=${tick.interval}s)`)
+          );
+        }
+      },
+    });
+  } catch (err) {
+    if (isJson) {
+      emitJsonError('login', err, { server_url: serverUrl });
+    } else {
+      console.error(chalk.red(`\n❌ ${err.message}`));
+      if (err instanceof DeviceFlowError && err.code === 'access_denied') {
+        console.error(chalk.gray('   You (or another session) denied the request.'));
+      } else if (err instanceof DeviceFlowError && err.code === 'expired_token') {
+        console.error(chalk.gray('   Run `spaps login` again to retry.'));
+      }
+    }
+    process.exit(1);
+  }
+
+  const nowSec = Math.floor(Date.now() / 1000);
+  const expiresAt = tokenPayload.expires_in
+    ? nowSec + Number(tokenPayload.expires_in)
+    : null;
+
+  setCredentials(serverUrl, {
+    access_token: tokenPayload.access_token,
+    refresh_token: tokenPayload.refresh_token || null,
+    token_type: tokenPayload.token_type || 'Bearer',
+    expires_in: tokenPayload.expires_in || null,
+    expires_at: expiresAt,
+    user_id: tokenPayload.user_id || null,
+    client_id: clientId,
+  });
+
+  if (isJson) {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          command: 'login',
+          server_url: serverUrl,
+          client_id: clientId,
+          user_id: tokenPayload.user_id || null,
+          expires_at: expiresAt,
+          credentials_path: CREDENTIALS_PATH,
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  console.log();
+  console.log(chalk.green('✅ Logged in to ') + chalk.cyan(serverUrl));
+  if (tokenPayload.user_id) {
+    console.log(chalk.gray(`   user_id: ${tokenPayload.user_id}`));
+  }
+  console.log(
+    chalk.gray(`   credentials saved to ${CREDENTIALS_PATH} (mode 0600)`)
+  );
+  console.log();
+}
+
+async function logoutHandler({ options }) {
+  const isJson = Boolean(options.json);
+  const serverUrl = resolveServerUrl(options);
+  const creds = getCredentials(serverUrl);
+
+  if (!creds || !creds.access_token) {
+    if (isJson) {
+      console.log(
+        JSON.stringify(
+          {
+            success: true,
+            command: 'logout',
+            server_url: serverUrl,
+            already_logged_out: true,
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+    console.log(chalk.yellow(`⚠️  Not currently logged in to ${serverUrl}`));
+    return;
+  }
+
+  // Best-effort server-side revoke. We intentionally do not refresh the access
+  // token if it has expired — the point of logout is to drop the session, and
+  // a failed revoke still clears local credentials.
+  let serverRevoked = false;
+  let revokeError = null;
+  try {
+    const res = await authFetch('/auth/logout', {
+      serverUrl,
+      method: 'POST',
+      body: creds.refresh_token ? { refresh_token: creds.refresh_token } : {},
+      allowRefresh: false,
+    });
+    serverRevoked = res.status >= 200 && res.status < 300;
+    if (!serverRevoked) {
+      revokeError = `HTTP ${res.status}`;
+    }
+  } catch (err) {
+    revokeError = err.message || String(err);
+  }
+
+  clearCredentials(serverUrl);
+
+  if (isJson) {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          command: 'logout',
+          server_url: serverUrl,
+          server_revoked: serverRevoked,
+          revoke_error: revokeError,
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  console.log(chalk.green(`✅ Logged out of ${serverUrl}`));
+  if (!serverRevoked) {
+    console.log(
+      chalk.gray('   (server-side revoke failed — local credentials cleared)')
+    );
+  }
+}
+
+async function whoamiHandler({ options }) {
+  const isJson = Boolean(options.json);
+  const serverUrl = resolveServerUrl(options);
+
+  let res;
+  try {
+    res = await authFetch('/auth/user', { serverUrl, method: 'GET' });
+  } catch (err) {
+    if (isJson) {
+      emitJsonError('whoami', err, { server_url: serverUrl });
+    } else {
+      console.error(chalk.red(`\n❌ ${err.message}`));
+      if (err.code === 'NOT_AUTHENTICATED') {
+        console.error(chalk.gray('   Run: npx spaps login'));
+      } else if (err.code === 'SESSION_EXPIRED') {
+        console.error(chalk.gray('   Run: npx spaps login   (your session expired)'));
+      }
+    }
+    process.exit(err.code === 'NOT_AUTHENTICATED' || err.code === 'SESSION_EXPIRED' ? 2 : 1);
+  }
+
+  if (res.status >= 400) {
+    const msg =
+      (res.data && (res.data.detail || res.data.message)) || `HTTP ${res.status}`;
+    const code = (res.data && res.data.code) || `HTTP_${res.status}`;
+    if (isJson) {
+      console.log(
+        JSON.stringify(
+          {
+            success: false,
+            command: 'whoami',
+            server_url: serverUrl,
+            status: res.status,
+            error: { code, message: msg },
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.error(chalk.red(`\n❌ ${msg}`));
+    }
+    process.exit(1);
+  }
+
+  const user = res.data && res.data.user ? res.data.user : res.data;
+
+  if (isJson) {
+    console.log(
+      JSON.stringify(
+        { success: true, command: 'whoami', server_url: serverUrl, user },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  console.log();
+  console.log(chalk.bold('Logged in as:'));
+  console.log(
+    '  ' + chalk.cyan(user.email || user.username || user.id || '(unknown)')
+  );
+  if (user.id) console.log(chalk.gray(`  id: ${user.id}`));
+  if (Array.isArray(user.roles) && user.roles.length) {
+    console.log(chalk.gray(`  roles: ${user.roles.join(', ')}`));
+  }
+  if (user.tier) console.log(chalk.gray(`  tier: ${user.tier}`));
+  console.log(chalk.gray(`  server: ${serverUrl}`));
+  console.log();
+}
+
+async function tokenHandler({ options }) {
+  const isJson = Boolean(options.json);
+  const serverUrl = resolveServerUrl(options);
+
+  // Env-var bypass (CI): print it and exit. Skips file read/write entirely.
+  if (process.env.SPAPS_ACCESS_TOKEN) {
+    if (isJson) {
+      console.log(
+        JSON.stringify(
+          {
+            success: true,
+            command: 'token',
+            source: 'env',
+            access_token: process.env.SPAPS_ACCESS_TOKEN,
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+    process.stdout.write(process.env.SPAPS_ACCESS_TOKEN + '\n');
+    return;
+  }
+
+  const creds = getCredentials(serverUrl);
+  if (!creds || !creds.access_token) {
+    const msg = `Not authenticated to ${serverUrl}. Run: npx spaps login`;
+    if (isJson) {
+      console.log(
+        JSON.stringify(
+          {
+            success: false,
+            command: 'token',
+            server_url: serverUrl,
+            error: { code: 'NOT_AUTHENTICATED', message: msg },
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.error(chalk.red(`❌ ${msg}`));
+    }
+    process.exit(2);
+  }
+
+  // If the token is within 30s of expiry, try a silent refresh so the caller
+  // gets a fresh token. If refresh fails, fall through and print whatever we
+  // have — the consumer will see a 401 and re-login.
+  const nowSec = Math.floor(Date.now() / 1000);
+  if (
+    creds.expires_at &&
+    creds.expires_at - 30 < nowSec &&
+    creds.refresh_token
+  ) {
+    try {
+      const refreshed = await refreshAccessToken({
+        serverUrl,
+        refreshToken: creds.refresh_token,
+      });
+      const newExpiresAt = refreshed.expires_in
+        ? nowSec + Number(refreshed.expires_in)
+        : null;
+      setCredentials(serverUrl, {
+        ...creds,
+        access_token: refreshed.access_token,
+        refresh_token: refreshed.refresh_token || creds.refresh_token,
+        expires_in: refreshed.expires_in || creds.expires_in,
+        expires_at: newExpiresAt,
+        token_type: refreshed.token_type || creds.token_type || 'Bearer',
+      });
+      if (isJson) {
+        console.log(
+          JSON.stringify(
+            {
+              success: true,
+              command: 'token',
+              source: 'refreshed',
+              access_token: refreshed.access_token,
+              expires_at: newExpiresAt,
+            },
+            null,
+            2
+          )
+        );
+      } else {
+        process.stdout.write(refreshed.access_token + '\n');
+      }
+      return;
+    } catch {
+      // fall through — print the stale token
+    }
+  }
+
+  if (isJson) {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          command: 'token',
+          source: 'stored',
+          access_token: creds.access_token,
+          expires_at: creds.expires_at || null,
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  process.stdout.write(creds.access_token + '\n');
+}
+
+module.exports = {
+  loginHandler,
+  logoutHandler,
+  whoamiHandler,
+  tokenHandler,
+};

package/src/auth/http.js

@@ -0,0 +1,74 @@
+function normalizeServerUrl(serverUrl) {
+  return String(serverUrl || '').trim().replace(/\/+$/, '');
+}
+
+function buildApiUrl(serverUrl, path) {
+  const normalizedPath = path.startsWith('/api/')
+    ? path
+    : `/api${path.startsWith('/') ? path : `/${path}`}`;
+  return `${normalizeServerUrl(serverUrl)}${normalizedPath}`;
+}
+
+function unwrapApiData(payload) {
+  if (
+    payload &&
+    typeof payload === 'object' &&
+    Object.prototype.hasOwnProperty.call(payload, 'success')
+  ) {
+    if (payload.success === true && Object.prototype.hasOwnProperty.call(payload, 'data')) {
+      return payload.data;
+    }
+    if (payload.success === false && Object.prototype.hasOwnProperty.call(payload, 'error')) {
+      return payload.error;
+    }
+  }
+
+  return payload;
+}
+
+function extractApiError(payload, status) {
+  const source = unwrapApiData(payload);
+
+  if (source && typeof source === 'object') {
+    if (typeof source.code === 'string' || typeof source.message === 'string') {
+      return {
+        code: source.code || `HTTP_${status}`,
+        message: source.message || `Request failed with status ${status}`,
+      };
+    }
+
+    if (
+      typeof source.error === 'string' ||
+      typeof source.error_description === 'string' ||
+      typeof source.detail === 'string'
+    ) {
+      return {
+        code: source.error || `HTTP_${status}`,
+        message:
+          source.error_description ||
+          source.detail ||
+          source.message ||
+          `Request failed with status ${status}`,
+      };
+    }
+  }
+
+  if (typeof source === 'string' && source.trim()) {
+    return {
+      code: `HTTP_${status}`,
+      message: source,
+    };
+  }
+
+  return {
+    code: `HTTP_${status}`,
+    message: `Request failed with status ${status}`,
+  };
+}
+
+module.exports = {
+  buildApiUrl,
+  extractApiError,
+  normalizeServerUrl,
+  unwrapApiData,
+};