@jacebenson/jsn 4.3.13-dev.71.1 → 4.3.13-dev.72.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.13-dev.71.1",
+  "version": "4.3.13-dev.72.1",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/src/app.js

@@ -8,6 +8,7 @@
 // command handlers that already call them.
 
 import { AuthManager } from './auth.js';
+import { createAuthRecovery } from './auth-recovery.js';
 import { SDKClient } from './sdk.js';
 import { OutputWriter, FormatAuto, FormatJSON, FormatMarkdown, FormatQuiet, FormatStyled, hyperlink } from './output.js';
 import { saveConfig } from './config.js';
@@ -53,8 +54,11 @@ export class App {
 
   /** Build (or rebuild) the SDK client for an instance + session. */
   _buildSdk(instance, session = this.session) {
-    this.sdk = new SDKClient(instance, this.auth, {
+    this.sdk = new SDKClient(instance, this.auth.createProfileProvider(instance, {
+      username: session?.username, authMethod: session?.profile?.auth_method,
+    }), {
       domain: session?.domain || '',
+      recovery: createAuthRecovery({ app: this, session }),
     });
   }
 

package/src/auth-recovery.js

@@ -0,0 +1,74 @@
+import { errAPI } from './errors.js';
+import { canUsePicker, quoteShellArg } from './helpers.js';
+import { confirm } from './prompts.js';
+
+// Recovery is scoped to the SDK's resolved identity, never the mutable default.
+// error supplies the same safe guidance if the single retry is also rejected.
+export function createAuthRecovery({ app, session, argv = () => app._authArgv || {},
+  canInteract = canUsePicker, prompt = confirm,
+  renewBrowser = async (request, targetApp) => {
+    const { refreshProfile } = await import('./commands/auth.js');
+    return refreshProfile(request, targetApp);
+  },
+}) {
+  const { instance, profileName, username, profile } = session;
+  const target = profileName ? `--profile ${quoteShellArg(profileName)}` : quoteShellArg(instance);
+  const label = profileName ? `profile ${quoteShellArg(profileName)}` : 'the active profile';
+  function failure(method = profile?.auth_method) {
+    const error = errAPI(401, '');
+    const login = `jsn auth login ${target}`;
+    error.message = `Authentication rejected for ${label} (HTTP 401).`;
+    error.profile = profileName || null;
+    error.recovery = method === 'basic'
+      ? `jsn auth login --basic ${quoteShellArg(instance)}${profileName ? ` --profile ${quoteShellArg(profileName)}` : ''}`
+      : method === 'gck' ? `jsn auth refresh ${target} --browser`
+      : method === 'oauth' ? `jsn auth refresh ${target}` : login;
+    error.hint = method === 'basic'
+      ? `Set SN_USERNAME/SN_PASSWORD to the correct credentials, then run: ${error.recovery}`
+      : method === 'oauth'
+        ? `Run interactively: ${error.recovery}. If refresh fails, run: ${login}`
+        : `Run: ${error.recovery}`;
+    return error;
+  }
+  // Keep the settled promise too: this provider gets only one recovery attempt.
+  let recoveryAttempt;
+  const provider = {
+    error: failure(),
+    async recover({ status }) {
+      if (status !== 401) return false;
+      return recoveryAttempt ??= recoverOnce();
+    },
+  };
+  async function recoverOnce() {
+    let creds;
+    try {
+      creds = await app.auth.getCredentialsFor(instance, username, {
+        username, authMethod: profile?.auth_method, refresh: false,
+      });
+    } catch { throw provider.error; }
+    const method = profile?.auth_method || creds.auth_method;
+    provider.error = failure(method);
+    if (method === 'oauth' && creds.refresh_token) {
+      try {
+        await app.auth.refreshToken(instance, creds, username ?? null);
+        return true;
+      } catch { throw provider.error; }
+    }
+    if (method === 'gck' && profileName && ['auto', 'confirm'].includes(profile?.reauth ?? 'confirm')
+      && canInteract(app, argv())) {
+      try {
+        if ((profile?.reauth ?? 'confirm') === 'confirm'
+          && !await prompt({ message: `Sign in again in a browser for ${label}?`, default: false })) throw provider.error;
+        // Reuse the canonical GCK refresh/login operation without emitting a
+        // second success envelope or replacing the in-flight command's SDK.
+        const targetApp = Object.create(app);
+        targetApp.ok = () => {};
+        targetApp.sdk = app.getSDKForProfile(instance, { profile, authMethod: 'gck', username });
+        await renewBrowser({ profile: profileName, browser: true }, targetApp);
+        return true;
+      } catch { throw provider.error; }
+    }
+    throw provider.error;
+  }
+  return provider;
+}

package/src/cli.js

@@ -213,6 +213,7 @@ export function buildCLI() {
               hint: 'Run "jsn auth status" to list profiles.',
             });
           }
+          app._authArgv = argv;
           applySession(app, session);
         } catch (err) {
           guardExit(argv, { code: err.code || 'usage', message: err.message, hint: err.hint });

package/src/commands/auth.js

@@ -382,13 +382,18 @@ export async function modifyProfile(app, argv = {}) {
   const name = argv.name || argv.profile || await pickProfile(app, 'Modify which profile?', argv);
   const profile = app.config.profiles?.[name];
   if (!profile) throw new Error(`Profile not found: ${name}`);
-  const explicitSettings = ['read-only', 'skip-confirmations', 'include-counts'].some(flag => argv[flag] !== undefined);
+  if (argv.reauth !== undefined && !['auto', 'confirm', 'never'].includes(argv.reauth)) {
+    throw errUsage('--reauth must be auto, confirm, or never.');
+  }
+  const explicitSettings = ['read-only', 'skip-confirmations', 'include-counts', 'reauth'].some(flag => argv[flag] !== undefined);
   if (explicitSettings) {
     if (argv.domain !== undefined) throw errUsage('Set profile preferences and domain separately.');
     const updated = await configureProfileOptions({ ...profile }, argv);
+    if (argv.reauth !== undefined) updated.reauth = argv.reauth;
     app.config.profiles[name] = updated;
     await saveConfig(app.config);
-    app.ok({ profile: name, read_only: updated.read_only === true, confirm_deletes: updated.skip_confirmations !== true, include_counts: updated.include_counts !== false },
+    app.ok({ profile: name, read_only: updated.read_only === true, confirm_deletes: updated.skip_confirmations !== true, include_counts: updated.include_counts !== false,
+      ...(argv.reauth !== undefined ? { reauth: updated.reauth } : {}) },
       { summary: `Settings saved for ${name}` });
     return;
   }
@@ -1134,6 +1139,7 @@ export function authCmd(wrap) {
             .option('read-only', { type: 'boolean', describe: 'Set read-only access (use --no-read-only to allow writes)' })
             .option('include-counts', { type: 'boolean', describe: 'Set result counts (use --no-include-counts to disable)' })
             .option('confirm-deletes', { type: 'boolean', describe: 'Set delete confirmations (use --no-confirm-deletes to disable)' })
+            .option('reauth', { type: 'string', choices: ['auto', 'confirm', 'never'], describe: 'Browser recovery policy: auto, confirm (default), or never; interactive only' })
             .option('skip-confirmations', { type: 'boolean', describe: 'Compatibility flag: disable delete confirmations' })
             .positional('name', {
               describe: 'Profile name to modify',

package/src/errors.js

@@ -77,6 +77,16 @@ export function errNetwork(cause) {
 }
 
 export function errAPI(status, msg) {
+  // Authentication/authorization bodies can echo credentials. Never render them.
+  if (status === 401) {
+    const error = new AppError(CodeAuth, 'Authentication rejected for the active profile (HTTP 401).', 'Run: jsn auth login', 401);
+    error.recovery = 'jsn auth login';
+    return error;
+  }
+  if (status === 403) {
+    return new AppError(CodeForbidden, 'Access forbidden (HTTP 403).',
+      'This is an authorization/ACL/role problem, not a login problem. Check access to this endpoint.', 403);
+  }
   let hint = 'Check the API documentation for this endpoint.';
   if (status >= 500) {
     hint = 'The ServiceNow instance may be experiencing issues. Try again later.';
@@ -229,6 +239,11 @@ export function renderAppError(err, { app = null, argv = null, identifier = '' }
     return { stream: 'stderr', text, exitCode: 1 };
   }
 
+  if (code === CodeForbidden) {
+    if (resolveJsonMode(app, argv) && app) return { stream: 'stdout', text: null, exitCode: 1, appErr: true };
+    return { stream: 'stderr', text: `Error (forbidden): ${err.message}\n\nHint: ${err.hint}\n`, exitCode: 1 };
+  }
+
   if (code === CodeConfirmationRequired) {
     // Structured error for AI agents / piped consumers: the JSON envelope
     // goes to stdout (where tooling reads) so the agent can surface the

package/src/output.js

@@ -160,6 +160,11 @@ export class OutputWriter {
     const format = this.effectiveFormat();
     const e = error.code ? error : { code: 'unknown', message: String(error), hint: '' };
     const resp = { ok: false, error: e.message, code: e.code, hint: e.hint || '' };
+    if (e.status === 401 || e.status === 403) resp.status = e.status;
+    if (e.recovery) {
+      resp.recovery = e.recovery;
+      if (Object.hasOwn(e, 'profile')) resp.profile = e.profile;
+    }
     switch (format) {
       case FormatJSON:
       case FormatQuiet:

package/src/sdk.js

@@ -47,6 +47,7 @@ export class SDKClient {
   constructor(baseURL, authProvider, opts = {}) {
     this.baseURL = baseURL.replace(/\/$/, '');
     this.authProvider = authProvider;
+    this.recovery = opts.recovery;
     this.timeout = opts.timeout || DEFAULT_TIMEOUT;
     this.domain = opts.domain || '';
     this.oauthCookies = null;
@@ -100,23 +101,42 @@ export class SDKClient {
   async _withAuthenticatedRequest(endpoint, opts, {
     timeout = this.timeout, prepare, skipOAuthSession = false, normalizeErrors = false,
   }, consume = (response) => response) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeout);
-    try {
-      const req = new Request(endpoint, { ...opts, signal: controller.signal });
-      if (prepare) prepare(req);
-      await this._setAuth(req, { skipOAuthSession });
-      return await consume(await fetch(req));
-    } catch (err) {
-      if (normalizeErrors) {
-        if (err.name === 'AbortError') throw errNetwork(new Error('Request timed out'));
-        if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND' || err.code === 'ETIMEDOUT') {
-          throw errNetwork(err);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout);
+      let rejection;
+      try {
+        const req = new Request(endpoint, { ...opts, signal: controller.signal });
+        if (prepare) prepare(req);
+        await this._setAuth(req, { skipOAuthSession });
+        const response = await fetch(req);
+        if (!skipOAuthSession && response.status === 401 && this.recovery) {
+          // Only a definitive HTTP rejection permits replay, including POST.
+          // Do not consume/echo the provider's potentially sensitive body.
+          rejection = { status: response.status, method: req.method, url: req.url };
+          await response.body?.cancel();
+        } else {
+          return await consume(response);
         }
+      } catch (err) {
+        if (normalizeErrors) {
+          if (err.name === 'AbortError') throw errNetwork(new Error('Request timed out'));
+          if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND' || err.code === 'ETIMEDOUT') {
+            throw errNetwork(err);
+          }
+        }
+        throw err;
+      } finally {
+        clearTimeout(timer);
       }
-      throw err;
-    } finally {
-      clearTimeout(timer);
+      // Browser renewal has its own existing hard timeout. Never leave a
+      // request timeout running while waiting for the human to authenticate.
+      if (attempt === 0 && await this.recovery.recover(rejection)) {
+        this.oauthCookies = null;
+        this.sessionUserToken = '';
+        continue;
+      }
+      throw this.recovery.error || errAPI(401, '');
     }
   }