spaps 0.9.2 → 0.9.3

package/README.md

@@ -276,7 +276,11 @@ The CLI no longer assumes a built-in `spaps-cli` application slug. Resolve the c
 - repo-local `.spaps/app.json`
 - `/health/local-mode` test application metadata
 
-Authenticated follow-up calls such as `whoami`, `logout`, and token refresh still need a normal SPAPS app key when the server is not in local mode. The CLI resolves that key from:
+Public-client device-flow sessions store `client_id` and refresh keylessly with
+`{ refresh_token, client_id }` (no `X-API-Key`). Bearer-only endpoints such as
+`whoami`, `logout`, and `sessions` work without a repo-local key for those
+sessions. Confidential credentials (no `client_id`) still need an app key for
+refresh; the CLI resolves it from:
 
 - `SPAPS_API_KEY`
 - `NEXT_PUBLIC_SPAPS_API_KEY`
@@ -284,6 +288,19 @@ Authenticated follow-up calls such as `whoami`, `logout`, and token refresh stil
 - repo-local `.env.local`
 - repo-local `.env`
 
+### Machine and CI auth
+
+Automation should not default to operator device-flow sessions:
+
+| Pattern | When to use |
+| --- | --- |
+| `SPAPS_ACCESS_TOKEN` | Short-lived CI access. Highest precedence; skips `credentials.json` and refresh. |
+| Confidential secret key (`spaps_sec_...`) + refresh token (no `client_id`) | Refreshable machine/workload automation; refresh sends `X-API-Key`. |
+
+Avoid as machine-auth defaults: `spaps login` public-client refresh, publishable
+keys alone, or public offline access. Public-client refresh is for human/operator
+CLI sessions; pre-DPoP refresh-token theft is not cryptographically prevented.
+
 Examples:
 
 ```bash

package/assets/local-runtime/scripts/fetch-prod-db.sh

@@ -27,6 +27,27 @@ err() {
   printf '\n%s %s\n' "❌" "$1" >&2
 }
 
+file_mtime_epoch() {
+  local path="$1"
+  local mtime
+
+  # Probe GNU coreutils first (`stat -c %Y`), then BSD/macOS (`stat -f %m`).
+  # The two flag dialects are mutually incompatible: `stat -f` on GNU means
+  # "file system status" and prints multi-line garbage, so we must validate
+  # that we captured a bare epoch integer before trusting it.
+  if mtime=$(stat -c %Y "${path}" 2>/dev/null) && [[ "${mtime}" =~ ^[0-9]+$ ]]; then
+    printf '%s\n' "${mtime}"
+    return 0
+  fi
+
+  if mtime=$(stat -f %m "${path}" 2>/dev/null) && [[ "${mtime}" =~ ^[0-9]+$ ]]; then
+    printf '%s\n' "${mtime}"
+    return 0
+  fi
+
+  return 1
+}
+
 resolve_prod_host() {
   local candidate
   local candidates=("${PRIMARY_PROD_HOST}")
@@ -51,9 +72,13 @@ if [[ -f "${PROD_DUMP}" ]]; then
       info "SPAPS_PROD_DB_FRESH=1 set, fetching fresh dump from production..."
       ;;
     *)
-      DUMP_AGE=$(( $(date +%s) - $(stat -f %m "${PROD_DUMP}" 2>/dev/null || stat -c %Y "${PROD_DUMP}" 2>/dev/null) ))
-      DUMP_AGE_HOURS=$(( DUMP_AGE / 3600 ))
-      info "Using cached prod dump (${DUMP_AGE_HOURS}h old): ${PROD_DUMP}"
+      if DUMP_MTIME="$(file_mtime_epoch "${PROD_DUMP}")"; then
+        DUMP_AGE=$(( $(date +%s) - DUMP_MTIME ))
+        DUMP_AGE_HOURS=$(( DUMP_AGE / 3600 ))
+        info "Using cached prod dump (${DUMP_AGE_HOURS}h old): ${PROD_DUMP}"
+      else
+        info "Using cached prod dump: ${PROD_DUMP}"
+      fi
       info "Run with SPAPS_PROD_DB_FRESH=1 to fetch fresh data."
       exit 0
       ;;

package/bin/spaps.js

@@ -38,6 +38,10 @@ function shouldRouteToHome(args) {
       continue;
     }
 
+    if (arg.startsWith('--port=') || arg.startsWith('--server-url=')) {
+      continue;
+    }
+
     if (flagsWithValues.has(arg)) {
       index += 1;
       continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Sweet Potato Authentication & Payment Service CLI - Docker Compose orchestrator for local Python/FastAPI SPAPS server with built-in admin middleware",
   "main": "src/index.js",
   "bin": {

package/src/auth/client.js

@@ -12,10 +12,17 @@ const { DEFAULT_PORT } = require('../config');
 const {
   getCredentials,
   setCredentials,
+  withCredentialsLockAsync,
 } = require('./credentials');
 const { resolveAuthApiKey } = require('./api-key');
 const { buildApiUrl, extractApiError, unwrapApiData } = require('./http');
 
+const AUTH_BEARER_ONLY_PREFIXES = [
+  '/auth/user',
+  '/auth/logout',
+  '/auth/sessions',
+];
+
 function resolveServerUrl(options = {}) {
   if (options.serverUrl) return String(options.serverUrl).replace(/\/+$/, '');
   if (process.env.SPAPS_API_URL) return String(process.env.SPAPS_API_URL).replace(/\/+$/, '');
@@ -23,7 +30,46 @@ function resolveServerUrl(options = {}) {
   return `http://localhost:${port}`;
 }
 
-function buildRequestHeaders(headers = {}, cwd = process.cwd()) {
+function normalizeApiPath(pathOrUrl) {
+  if (/^https?:\/\//.test(pathOrUrl)) {
+    try {
+      const pathname = new URL(pathOrUrl).pathname;
+      return pathname.startsWith('/api/')
+        ? pathname.slice('/api'.length)
+        : pathname;
+    } catch {
+      return pathOrUrl;
+    }
+  }
+  if (pathOrUrl.startsWith('/api/')) {
+    return pathOrUrl.slice('/api'.length);
+  }
+  return pathOrUrl.startsWith('/') ? pathOrUrl : `/${pathOrUrl}`;
+}
+
+function isAuthBearerOnlyPath(pathOrUrl) {
+  const normalized = normalizeApiPath(pathOrUrl).replace(/\/+$/, '') || '/';
+  return AUTH_BEARER_ONLY_PREFIXES.some(
+    (prefix) => normalized === prefix || normalized.startsWith(`${prefix}/`)
+  );
+}
+
+function isPublicClientCredentials(creds) {
+  return Boolean(creds && creds.client_id);
+}
+
+function shouldSkipApiKey({ storedCreds, pathOrUrl }) {
+  if (!isPublicClientCredentials(storedCreds)) {
+    return false;
+  }
+  return isAuthBearerOnlyPath(pathOrUrl);
+}
+
+function buildRequestHeaders(headers = {}, cwd = process.cwd(), options = {}) {
+  if (options.skipApiKey) {
+    return headers;
+  }
+
   const resolved = resolveAuthApiKey({ cwd });
   if (
     !resolved.apiKey ||
@@ -39,34 +85,172 @@ function buildRequestHeaders(headers = {}, cwd = process.cwd()) {
   };
 }
 
+function normalizeErrorToken(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+function enrichRefreshError(err, payload, status) {
+  const apiError = extractApiError(payload || {}, status);
+  const envelopeError =
+    payload &&
+    typeof payload === 'object' &&
+    payload.success === false &&
+    payload.error &&
+    typeof payload.error === 'object'
+      ? payload.error
+      : null;
+  const details = envelopeError?.details || null;
+  const stableCode =
+    (details && details.stable_code) ||
+    envelopeError?.stable_code ||
+    null;
+
+  const out = err instanceof Error ? err : new Error(apiError.message || String(err));
+  out.code = apiError.code || out.code || 'REFRESH_FAILED';
+  out.status = status;
+  out.stableCode = stableCode;
+  out.details = details;
+  out.message = apiError.message || out.message;
+  return out;
+}
+
+function isInteractionRequiredRefreshError(err) {
+  const code = normalizeErrorToken(err && err.code);
+  const stable = normalizeErrorToken(err && err.stableCode);
+  if (code === 'interaction_required' || stable === 'interaction_required') {
+    return true;
+  }
+  if (err && err.details && err.details.interaction_required === true) {
+    return true;
+  }
+  if (code === 'refresh_token_expired' || code === 'refresh_idle_ttl') {
+    return true;
+  }
+  return false;
+}
+
+function isRotationRaceRefreshError(err) {
+  const code = normalizeErrorToken(err && err.code);
+  const stable = normalizeErrorToken(err && err.stableCode);
+  return (
+    code === 'refresh_token_replay' ||
+    code === 'already_rotated' ||
+    code === 'rotation_in_progress' ||
+    stable === 'already_rotated' ||
+    stable === 'rotation_in_progress'
+  );
+}
+
+function tokenLooksFresh(creds, skewSec = 30) {
+  if (!creds || !creds.access_token) {
+    return false;
+  }
+  const nowSec = Math.floor(Date.now() / 1000);
+  if (!creds.expires_at) {
+    return true;
+  }
+  return creds.expires_at - skewSec >= nowSec;
+}
+
+function mergeRefreshedCredentials(existing, refreshed, nowSec) {
+  return {
+    ...existing,
+    access_token: refreshed.access_token,
+    refresh_token: refreshed.refresh_token || existing.refresh_token,
+    expires_in: refreshed.expires_in || existing.expires_in,
+    expires_at: refreshed.expires_in
+      ? nowSec + Number(refreshed.expires_in)
+      : existing.expires_at,
+    token_type: refreshed.token_type || existing.token_type || 'Bearer',
+    client_id: existing.client_id || null,
+    session_id: refreshed.session_id || existing.session_id || null,
+  };
+}
+
 async function refreshAccessToken({
   serverUrl,
   refreshToken,
+  clientId = null,
   axiosInstance = axios,
   headers = {},
   cwd = process.cwd(),
 }) {
+  const body = { refresh_token: refreshToken };
+  if (clientId) {
+    body.client_id = clientId;
+  }
+
   const res = await axiosInstance.post(
     buildApiUrl(serverUrl, '/auth/refresh'),
-    { refresh_token: refreshToken },
+    body,
     {
       headers: buildRequestHeaders(
         { 'Content-Type': 'application/json', ...headers },
-        cwd
+        cwd,
+        { skipApiKey: Boolean(clientId) }
       ),
       validateStatus: () => true,
     }
   );
   if (res.status >= 400) {
-    const apiError = extractApiError(res.data || {}, res.status);
-    const err = new Error(apiError.message || `refresh failed (HTTP ${res.status})`);
-    err.code = apiError.code || 'REFRESH_FAILED';
-    err.status = res.status;
-    throw err;
+    const baseErr = new Error(
+      extractApiError(res.data || {}, res.status).message ||
+        `refresh failed (HTTP ${res.status})`
+    );
+    throw enrichRefreshError(baseErr, res.data || {}, res.status);
   }
   return unwrapApiData(res.data);
 }
 
+async function performCredentialRefresh({
+  serverUrl,
+  cwd = process.cwd(),
+  axiosInstance = axios,
+  allowRotationRetry = true,
+}) {
+  return withCredentialsLockAsync(async () => {
+    const creds = getCredentials(serverUrl);
+    if (!creds || !creds.refresh_token) {
+      const err = new Error('Not authenticated. Run `spaps login` first.');
+      err.code = 'NOT_AUTHENTICATED';
+      throw err;
+    }
+
+    if (tokenLooksFresh(creds)) {
+      return creds;
+    }
+
+    const beforeAccessToken = creds.access_token;
+
+    try {
+      const refreshed = await refreshAccessToken({
+        serverUrl,
+        refreshToken: creds.refresh_token,
+        clientId: creds.client_id || null,
+        axiosInstance,
+        cwd,
+      });
+      const nowSec = Math.floor(Date.now() / 1000);
+      const updated = mergeRefreshedCredentials(creds, refreshed, nowSec);
+      setCredentials(serverUrl, updated);
+      return updated;
+    } catch (err) {
+      if (allowRotationRetry && isRotationRaceRefreshError(err)) {
+        const reread = getCredentials(serverUrl);
+        if (
+          reread &&
+          reread.access_token &&
+          reread.access_token !== beforeAccessToken &&
+          tokenLooksFresh(reread)
+        ) {
+          return reread;
+        }
+      }
+      throw err;
+    }
+  });
+}
+
 async function authFetch(
   pathOrUrl,
   {
@@ -96,6 +280,8 @@ async function authFetch(
     accessToken = storedCreds.access_token;
   }
 
+  const skipApiKey = shouldSkipApiKey({ storedCreds, pathOrUrl });
+
   const doRequest = (tokenToUse) =>
     axiosInstance({
       url,
@@ -105,7 +291,7 @@ async function authFetch(
         ...headers,
         Authorization: `Bearer ${tokenToUse}`,
         ...(body ? { 'Content-Type': 'application/json' } : {}),
-      }, cwd),
+      }, cwd, { skipApiKey }),
       validateStatus: () => true,
     });
 
@@ -125,28 +311,24 @@ async function authFetch(
     shouldAttemptRefresh
   ) {
     try {
-      const refreshed = await refreshAccessToken({
+      const updated = await performCredentialRefresh({
         serverUrl: base,
-        refreshToken: storedCreds.refresh_token,
         axiosInstance,
         cwd,
       });
-      const nowSec = Math.floor(Date.now() / 1000);
-      const newAccess = refreshed.access_token;
-      const newRefresh = refreshed.refresh_token || storedCreds.refresh_token;
-      setCredentials(base, {
-        ...storedCreds,
-        access_token: newAccess,
-        refresh_token: newRefresh,
-        expires_in: refreshed.expires_in || storedCreds.expires_in,
-        expires_at: refreshed.expires_in ? nowSec + Number(refreshed.expires_in) : null,
-        token_type: refreshed.token_type || storedCreds.token_type || 'Bearer',
-      });
-      res = await doRequest(newAccess);
+      res = await doRequest(updated.access_token);
     } catch (err) {
       if (err.code === 'INVALID_APPLICATION') {
         throw err;
       }
+      if (isInteractionRequiredRefreshError(err)) {
+        const authErr = new Error(
+          'Device login required. Run `spaps login` again.'
+        );
+        authErr.code = 'INTERACTION_REQUIRED';
+        authErr.cause = err;
+        throw authErr;
+      }
       const authErr = new Error('Session expired. Run `spaps login` again.');
       authErr.code = 'SESSION_EXPIRED';
       authErr.cause = err;
@@ -162,8 +344,16 @@ async function authFetch(
 }
 
 module.exports = {
+  AUTH_BEARER_ONLY_PREFIXES,
   buildRequestHeaders,
+  isAuthBearerOnlyPath,
+  isInteractionRequiredRefreshError,
+  isPublicClientCredentials,
+  isRotationRaceRefreshError,
+  mergeRefreshedCredentials,
+  performCredentialRefresh,
   resolveServerUrl,
   refreshAccessToken,
   authFetch,
+  tokenLooksFresh,
 };

package/src/auth/credentials.js

@@ -12,6 +12,8 @@ const os = require('node:os');
 const path = require('node:path');
 
 const SCHEMA_VERSION = 1;
+const DEFAULT_LOCK_TIMEOUT_MS = 10_000;
+const DEFAULT_STALE_LOCK_MS = 30_000;
 
 function defaultCredentialsPath() {
   if (process.env.SPAPS_CREDENTIALS_PATH) {
@@ -30,8 +32,123 @@ function emptyStore() {
   return { version: SCHEMA_VERSION, servers: {} };
 }
 
+function lockPathFor(target) {
+  return `${target}.lock`;
+}
+
+function isLockStale(lockPath, maxAgeMs = DEFAULT_STALE_LOCK_MS) {
+  try {
+    const stat = fs.statSync(lockPath);
+    return Date.now() - stat.mtimeMs > maxAgeMs;
+  } catch {
+    return false;
+  }
+}
+
+function spinWait(ms) {
+  const deadline = Date.now() + ms;
+  while (Date.now() < deadline) {
+    // Busy-wait briefly; credential ops are short-lived.
+  }
+}
+
+function acquireLockSync(
+  target,
+  timeoutMs = DEFAULT_LOCK_TIMEOUT_MS,
+  staleLockMs = DEFAULT_STALE_LOCK_MS
+) {
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  const lockPath = lockPathFor(target);
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    try {
+      const fd = fs.openSync(lockPath, 'wx');
+      fs.writeSync(
+        fd,
+        JSON.stringify({ pid: process.pid, acquired_at: Date.now() })
+      );
+      fs.closeSync(fd);
+      return lockPath;
+    } catch (err) {
+      if (err.code !== 'EEXIST') {
+        throw err;
+      }
+      if (isLockStale(lockPath, staleLockMs)) {
+        try {
+          fs.unlinkSync(lockPath);
+        } catch {
+          // Another process may have released the lock; retry.
+        }
+        continue;
+      }
+      spinWait(50);
+    }
+  }
+
+  const lockErr = new Error('Timed out acquiring credentials lock');
+  lockErr.code = 'CREDENTIALS_LOCK_TIMEOUT';
+  throw lockErr;
+}
+
+function releaseLockSync(lockPath) {
+  try {
+    fs.unlinkSync(lockPath);
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      throw err;
+    }
+  }
+}
+
 function createStore(filePath) {
   const target = filePath || defaultCredentialsPath();
+  let lockDepth = 0;
+  let activeLockPath = null;
+
+  function withCredentialsLock(fn, options = {}) {
+    if (lockDepth > 0) {
+      return fn();
+    }
+
+    activeLockPath = acquireLockSync(
+      target,
+      options.timeoutMs,
+      options.staleLockMs
+    );
+    lockDepth += 1;
+    try {
+      return fn();
+    } finally {
+      lockDepth -= 1;
+      if (lockDepth === 0) {
+        releaseLockSync(activeLockPath);
+        activeLockPath = null;
+      }
+    }
+  }
+
+  async function withCredentialsLockAsync(fn, options = {}) {
+    if (lockDepth > 0) {
+      return await fn();
+    }
+
+    activeLockPath = acquireLockSync(
+      target,
+      options.timeoutMs,
+      options.staleLockMs
+    );
+    lockDepth += 1;
+    try {
+      return await fn();
+    } finally {
+      lockDepth -= 1;
+      if (lockDepth === 0) {
+        releaseLockSync(activeLockPath);
+        activeLockPath = null;
+      }
+    }
+  }
 
   function loadAll() {
     try {
@@ -61,28 +178,34 @@ function createStore(filePath) {
   }
 
   function getCredentials(serverUrl) {
-    const data = loadAll();
-    return data.servers[normalizeServerUrl(serverUrl)] || null;
+    return withCredentialsLock(() => {
+      const data = loadAll();
+      return data.servers[normalizeServerUrl(serverUrl)] || null;
+    });
   }
 
   function setCredentials(serverUrl, creds) {
-    const data = loadAll();
-    data.servers[normalizeServerUrl(serverUrl)] = {
-      ...creds,
-      saved_at: Math.floor(Date.now() / 1000),
-    };
-    saveAll(data);
+    return withCredentialsLock(() => {
+      const data = loadAll();
+      data.servers[normalizeServerUrl(serverUrl)] = {
+        ...creds,
+        saved_at: Math.floor(Date.now() / 1000),
+      };
+      saveAll(data);
+    });
   }
 
   function clearCredentials(serverUrl) {
-    const data = loadAll();
-    const key = normalizeServerUrl(serverUrl);
-    if (data.servers[key]) {
-      delete data.servers[key];
-      saveAll(data);
-      return true;
-    }
-    return false;
+    return withCredentialsLock(() => {
+      const data = loadAll();
+      const key = normalizeServerUrl(serverUrl);
+      if (data.servers[key]) {
+        delete data.servers[key];
+        saveAll(data);
+        return true;
+      }
+      return false;
+    });
   }
 
   return {
@@ -90,8 +213,13 @@ function createStore(filePath) {
     getCredentials,
     setCredentials,
     clearCredentials,
+    withCredentialsLock,
+    withCredentialsLockAsync,
     _loadAll: loadAll,
     _saveAll: saveAll,
+    _acquireLockSync: () => acquireLockSync(target),
+    _releaseLockSync: (lockPath) => releaseLockSync(lockPath),
+    _lockPathFor: () => lockPathFor(target),
   };
 }
 
@@ -100,11 +228,17 @@ const defaultStore = createStore();
 
 module.exports = {
   SCHEMA_VERSION,
+  DEFAULT_LOCK_TIMEOUT_MS,
+  DEFAULT_STALE_LOCK_MS,
   createStore,
   defaultCredentialsPath,
   normalizeServerUrl,
+  lockPathFor,
   get CREDENTIALS_PATH() { return defaultStore.path; },
   getCredentials: (url) => defaultStore.getCredentials(url),
   setCredentials: (url, creds) => defaultStore.setCredentials(url, creds),
   clearCredentials: (url) => defaultStore.clearCredentials(url),
+  withCredentialsLock: (fn, options) => defaultStore.withCredentialsLock(fn, options),
+  withCredentialsLockAsync: (fn, options) =>
+    defaultStore.withCredentialsLockAsync(fn, options),
 };

package/src/auth/handlers.js

@@ -19,7 +19,12 @@ const {
   CREDENTIALS_PATH,
 } = require('./credentials');
 const { isHeadless, tryOpenBrowser } = require('./env');
-const { authFetch, resolveServerUrl, refreshAccessToken } = require('./client');
+const {
+  authFetch,
+  resolveServerUrl,
+  isInteractionRequiredRefreshError,
+  performCredentialRefresh,
+} = require('./client');
 const { resolveLoginClientId } = require('./client-id');
 const {
   fetchAuthMethods,
@@ -169,6 +174,7 @@ async function loginHandler({ options }) {
     expires_at: expiresAt,
     user_id: tokenPayload.user_id || null,
     client_id: clientId,
+    session_id: tokenPayload.session_id || null,
   });
 
   if (isJson) {
@@ -289,9 +295,17 @@ async function whoamiHandler({ options }) {
         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)'));
+      } else if (err.code === 'INTERACTION_REQUIRED') {
+        console.error(chalk.gray('   Run: npx spaps login   (device login required)'));
       }
     }
-    process.exit(err.code === 'NOT_AUTHENTICATED' || err.code === 'SESSION_EXPIRED' ? 2 : 1);
+    process.exit(
+      err.code === 'NOT_AUTHENTICATED' ||
+        err.code === 'SESSION_EXPIRED' ||
+        err.code === 'INTERACTION_REQUIRED'
+        ? 2
+        : 1
+    );
   }
 
   if (res.status >= 400) {
@@ -392,31 +406,45 @@ async function tokenHandler({ options }) {
     process.exit(2);
   }
 
+  const printTokenRefreshError = ({ code, message, expiresAt, cause }) => {
+    const loginCommand = `spaps login --server-url ${serverUrl}`;
+    if (isJson) {
+      console.log(
+        JSON.stringify(
+          {
+            success: false,
+            command: 'token',
+            server_url: serverUrl,
+            expires_at: expiresAt || null,
+            login_command: loginCommand,
+            error: {
+              code,
+              message,
+              ...(cause && cause.code ? { cause_code: cause.code } : {}),
+              ...(cause && cause.stableCode ? { cause_stable_code: cause.stableCode } : {}),
+              ...(cause && cause.status ? { cause_status: cause.status } : {}),
+            },
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.error(chalk.red(`❌ ${message}`));
+      console.error(chalk.gray(`   Run: ${loginCommand}`));
+    }
+    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.
+  // gets a fresh token. Never print an expired/stale token after refresh fails:
+  // downstream consumers otherwise surface confusing 401s.
   const nowSec = Math.floor(Date.now() / 1000);
-  if (
-    creds.expires_at &&
-    creds.expires_at - 30 < nowSec &&
-    creds.refresh_token
-  ) {
+  const tokenNeedsRefresh = Boolean(creds.expires_at && creds.expires_at - 30 < nowSec);
+  if (tokenNeedsRefresh && 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',
-      });
+      const updated = await performCredentialRefresh({ serverUrl });
+      const newExpiresAt = updated.expires_at || null;
       if (isJson) {
         console.log(
           JSON.stringify(
@@ -424,7 +452,7 @@ async function tokenHandler({ options }) {
               success: true,
               command: 'token',
               source: 'refreshed',
-              access_token: refreshed.access_token,
+              access_token: updated.access_token,
               expires_at: newExpiresAt,
             },
             null,
@@ -432,14 +460,35 @@ async function tokenHandler({ options }) {
           )
         );
       } else {
-        process.stdout.write(refreshed.access_token + '\n');
+        process.stdout.write(updated.access_token + '\n');
       }
       return;
-    } catch {
-      // fall through — print the stale token
+    } catch (err) {
+      if (isInteractionRequiredRefreshError(err)) {
+        printTokenRefreshError({
+          code: 'INTERACTION_REQUIRED',
+          expiresAt: creds.expires_at,
+          message: `Stored SPAPS session requires device login. Re-authenticate to ${serverUrl}.`,
+          cause: err,
+        });
+      }
+      printTokenRefreshError({
+        code: 'TOKEN_REFRESH_FAILED',
+        expiresAt: creds.expires_at,
+        message: `Stored SPAPS access token is expired or expiring, and refresh failed. Re-authenticate to ${serverUrl}.`,
+        cause: err,
+      });
     }
   }
 
+  if (tokenNeedsRefresh) {
+    printTokenRefreshError({
+      code: 'TOKEN_EXPIRED',
+      expiresAt: creds.expires_at,
+      message: `Stored SPAPS access token is expired or expiring, and no refresh token is available. Re-authenticate to ${serverUrl}.`,
+    });
+  }
+
   if (isJson) {
     console.log(
       JSON.stringify(

package/src/cli-dispatcher.js

@@ -516,7 +516,8 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
         .option('--user-id <id>', 'User id for log attribution')
         .option('--owner-id <id>', 'Owner id for log attribution')
         .option('--subject-override <text>', 'Subject override')
-        .option('--body-override <text>', 'Body override'),
+        .option('--body-override <text>', 'Body override')
+        .option('--idempotency-key <key>', 'Idempotency key for retry-safe sends'),
     (opts) => ({
       templateKey: opts.templateKey || null,
       to: opts.to || null,
@@ -525,6 +526,7 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
       ownerId: opts.ownerId || null,
       subjectOverride: opts.subjectOverride || null,
       bodyOverride: opts.bodyOverride || null,
+      idempotencyKey: opts.idempotencyKey || null,
     })
   );
 

package/src/error-handler.js

@@ -257,7 +257,7 @@ function formatError(error, context = {}) {
   // Additional help
   output.push(chalk.gray('\n📚 For more help:'));
   output.push(chalk.gray('   • Documentation: https://sweetpotato.dev/docs'));
-  output.push(chalk.gray('   • GitHub Issues: https://github.com/yourusername/sweet-potato/issues'));
+  output.push(chalk.gray('   • GitHub Issues: https://github.com/build000r/sweet-potato/issues'));
   output.push(chalk.gray('   • Discord: https://discord.gg/sweetpotato\n'));
   
   return output.join('\n');
@@ -285,7 +285,7 @@ function formatJsonError(error, context = {}) {
     },
     help: {
       docs: 'https://sweetpotato.dev/docs',
-      issues: 'https://github.com/yourusername/sweet-potato/issues',
+      issues: 'https://github.com/build000r/sweet-potato/issues',
       discord: 'https://discord.gg/sweetpotato'
     }
   };

package/src/handlers.js

@@ -27,6 +27,28 @@ const loadProjectScaffolder = lazy(() => require('./project-scaffolder'));
 const loadAuthCommandHandlers = lazy(() => require('./auth/handlers'));
 const loadDomainCli = lazy(() => require('./domain-cli'));
 
+function openExternalUrl(url, { spawnImpl = null, platform = process.platform } = {}) {
+  const spawn = spawnImpl || require('child_process').spawn;
+  let command;
+  let args;
+
+  if (platform === 'darwin') {
+    command = 'open';
+    args = [url];
+  } else if (platform === 'win32') {
+    command = 'rundll32';
+    args = ['url.dll,FileProtocolHandler', url];
+  } else {
+    command = 'xdg-open';
+    args = [url];
+  }
+
+  const child = spawn(command, args, { stdio: 'ignore', detached: true });
+  child.on?.('error', () => {});
+  child.unref?.();
+  return { command, args };
+}
+
 function createHandlers(version, logo) {
   function invalidArgument(message) {
     const error = new Error(message);
@@ -129,10 +151,8 @@ function createHandlers(version, logo) {
         await server.start();
 
         if (options.open && !isJson) {
-          const { exec } = require('child_process');
           const url = `http://localhost:${options.port}/docs`;
-          const start = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-          exec(`${start} ${url}`);
+          openExternalUrl(url);
         }
 
         // Set up shutdown handler
@@ -170,12 +190,14 @@ function createHandlers(version, logo) {
       const status = await getServerStatus(options.port);
       if (options.json) {
         console.log(JSON.stringify(status));
+        if (!status.running) process.exitCode = 1;
       } else {
         if (!status.running) {
           console.log(chalk.red('\n❌ SPAPS server is not running'));
           console.log('Start it with:');
           console.log(chalk.cyan(`  npx spaps local --port ${options.port}`));
           console.log();
+          process.exitCode = 1;
         } else {
           console.log(chalk.green('\n✅ SPAPS server is running!\n'));
           console.log('  URL:', chalk.cyan(status.url));
@@ -938,6 +960,7 @@ async function emailHandler({ options }) {
       assignIfDefined(body, 'owner_id', options.ownerId);
       assignIfDefined(body, 'subject_override', options.subjectOverride);
       assignIfDefined(body, 'body_override', options.bodyOverride);
+      assignIfDefined(body, 'idempotency_key', options.idempotencyKey);
 
       const result = await callEndpoint({ options, method: 'POST', path: '/api/email/send', body });
       emit({ intent: 'email.send', result, isJson });
@@ -1372,4 +1395,4 @@ async function capabilityHandler({ name, options }) {
   }
 }
 
-module.exports = { createHandlers };
+module.exports = { createHandlers, openExternalUrl };

package/src/local-server.js

@@ -559,6 +559,12 @@ class LocalServer {
   }
 
   printConnectionInfo({ restorePlan, restoreApplied }) {
+    // Local mode authenticates by header-selected persona, not by
+    // email/password. Picking a persona is what actually works against the
+    // running server (see middleware/local_mode.py + spaps_deps.py), so we
+    // surface the X-Test-User / ?_user contract rather than fake credentials.
+    const localModeEnabled =
+      String(this.composeEnv.SPAPS_LOCAL_MODE ?? 'true').trim().toLowerCase() === 'true';
     const connectionInfo = {
       SPAPS_API_URL: this.apiUrl,
       SPAPS_API_KEY: 'spaps_local_development_key',
@@ -567,10 +573,26 @@ class LocalServer {
       data_source: this.dataSource,
       restore_applied: Boolean(restoreApplied),
       restore_source: restorePlan ? restorePlan.source : null,
-      test_users: {
-        admin: { email: 'admin@spaps.dev', password: 'Admin1234x' },
-        user: { email: 'user@spaps.dev', password: 'User1234x' },
-        premium: { email: 'premium@spaps.dev', password: 'Premium1234x' },
+      test_personas: {
+        local_mode_enabled: localModeEnabled,
+        select_via: 'X-Test-User: <persona> header (or ?_user=<persona> query param)',
+        default_persona: 'user',
+        note: 'Local-mode personas are header-selected; there are no password logins.',
+        personas: [
+          { persona: 'user', header: 'X-Test-User: user', email: 'user@localhost', tier: 'free' },
+          {
+            persona: 'admin',
+            header: 'X-Test-User: admin',
+            email: 'buildooor@gmail.com',
+            tier: 'enterprise',
+          },
+          {
+            persona: 'premium',
+            header: 'X-Test-User: premium',
+            email: 'premium@localhost',
+            tier: 'premium',
+          },
+        ],
       },
     };
 
@@ -614,10 +636,25 @@ class LocalServer {
     console.log(`   ${chalk.bold('Application ID:')} ${connectionInfo.SPAPS_APPLICATION_ID}`);
     console.log(`   ${chalk.bold('Self-service:')}  ${connectionInfo.SELF_SERVICE_PASSWORD}`);
     console.log();
-    console.log(chalk.cyan('👥 Test Users:'));
-    console.log(`   ${chalk.bold('Admin:')}    ${connectionInfo.test_users.admin.email} / ${connectionInfo.test_users.admin.password}`);
-    console.log(`   ${chalk.bold('User:')}     ${connectionInfo.test_users.user.email} / ${connectionInfo.test_users.user.password}`);
-    console.log(`   ${chalk.bold('Premium:')}  ${connectionInfo.test_users.premium.email} / ${connectionInfo.test_users.premium.password}`);
+    const { test_personas: testPersonas } = connectionInfo;
+    console.log(chalk.cyan('👥 Test Personas (local mode):'));
+    if (testPersonas.local_mode_enabled) {
+      console.log(chalk.dim('   Select one with the X-Test-User header (or ?_user= query param).'));
+      for (const persona of testPersonas.personas) {
+        const label = `${persona.persona}:`.padEnd(9);
+        console.log(
+          `   ${chalk.bold(label)} X-Test-User: ${chalk.bold(persona.persona)}  (${persona.email}, tier=${persona.tier})`
+        );
+      }
+      console.log(
+        chalk.dim(`   Default persona when no header is sent: ${testPersonas.default_persona}.`)
+      );
+      console.log(chalk.dim(`   Example: curl -H "X-Test-User: admin" ${this.apiUrl}/api/auth/user`));
+    } else {
+      console.log(
+        chalk.dim('   Local-mode persona bypass is disabled (SPAPS_LOCAL_MODE != true); use real auth flows.')
+      );
+    }
     console.log();
 
     if (this.detach) {