unbound-cli 1.19.0 → 1.20.1

package/README.md

@@ -54,6 +54,9 @@ Only your API key is needed. Run with `sudo` to let the discovery step scan all
 | `unbound login` | Sign in via browser |
 | `unbound login --api-key <key>` | Sign in with an API key (non-interactive) |
 | `unbound login --domain <domain>` | Sign in via a custom domain |
+| `unbound login --role <name>` | Browser sign-in with a token scoped to a console role (`admin`, `analytics-viewer`, `manager`, or a custom role) |
+| `unbound login --permissions <list>` | Browser sign-in with a token scoped per area, e.g. `analytics=view,logs=view` |
+| `unbound login --expires-in-days <n>` | Token lifetime for browser sign-in: 7, 30, 60 or 90 (default 90) |
 | `unbound logout` | Remove the CLI key from the OS keychain |
 | `unbound status` | Show CLI status, role, and connected tools |
 | `unbound doctor` | Diagnose per-tool health (config, hook, env) and API key |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "1.19.0",
+  "version": "1.20.1",
   "description": "CLI tool for Unbound - AI Gateway management",
   "main": "src/index.js",
   "bin": {

package/src/auth-pages.js

@@ -169,12 +169,13 @@ function successPage({ email, orgName } = {}) {
 }
 
 /** Failure page for a callback that arrived without an api_key. */
-function failurePage() {
+function failurePage(reason) {
+  const detail = reason ? `<p>${escapeHtml(reason)}</p>` : '';
   return renderPage({
     title: 'Authentication Failed | Unbound',
     icon: CROSS_ICON,
     heading: 'Authentication Failed',
-    body: '<p>You can close this tab and try again from the terminal.</p>',
+    body: `${detail}<p>You can close this tab and try again from the terminal.</p>`,
   });
 }
 

package/src/auth.js

@@ -2,7 +2,9 @@
  * Shared browser-based authentication flow.
  * Used by both `login` and `setup` commands.
  */
+const crypto = require('crypto');
 const http = require('http');
+const os = require('os');
 const { URL } = require('url');
 const authPages = require('./auth-pages');
 const config = require('./config');
@@ -32,8 +34,10 @@ function warnIfNotStored(stored) {
  * @param {string} frontendUrl - The frontend URL to open
  * @returns {Promise<{email: string, orgName: string}>}
  */
-async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
+async function loginWithBrowser(frontendUrl, { open: openFn, scope = {} } = {}) {
   const server = http.createServer();
+  // One-time nonce: only the redirect the dashboard was handed can complete this login.
+  const state = crypto.randomBytes(16).toString('hex');
   let callbackResolve;
   let callbackReject;
 
@@ -72,7 +76,7 @@ async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
   function respondAndShutdown(res, statusCode, html) {
     res.on('finish', shutdownServer);
     res.on('close', shutdownServer);
-    res.writeHead(statusCode, { 'Content-Type': 'text/html; charset=utf-8', 'Connection': 'close' });
+    res.writeHead(statusCode, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store', 'Connection': 'close' });
     res.end(html);
   }
 
@@ -83,6 +87,14 @@ async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
   let callbackHandled = false;
   let stored;
 
+  // Compare byte lengths, not string lengths: a multi-byte candidate would make timingSafeEqual throw.
+  function stateMatches(candidate) {
+    if (typeof candidate !== 'string') return false;
+    const given = Buffer.from(candidate);
+    const expected = Buffer.from(state);
+    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
+  }
+
   server.on('request', (req, res) => {
     const url = new URL(req.url, `http://localhost`);
 
@@ -92,6 +104,13 @@ async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
       return;
     }
 
+    // A request without this login's nonce is not the dashboard's redirect: answer it and keep waiting.
+    if (!stateMatches(url.searchParams.get('state'))) {
+      res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store', 'Connection': 'close' });
+      res.end(authPages.failurePage('Invalid login callback'));
+      return;
+    }
+
     if (callbackHandled) {
       res.writeHead(409, { 'Connection': 'close' });
       res.end('Callback already processed');
@@ -102,10 +121,14 @@ async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
     const apiKey = url.searchParams.get('api_key');
     const email = url.searchParams.get('email');
     const orgName = url.searchParams.get('org');
+    // Nonce-gated, but the reason is still stripped of control characters before display as defence in depth.
+    const reason = (url.searchParams.get('error') || '').replace(/[\u0000-\u001f\u007f-\u009f]/g, '').slice(0, 200);
+    // `scope` echoes what the dashboard minted; an older dashboard sends none.
+    const grantedScope = url.searchParams.get('scope');
 
     if (!apiKey) {
-      respondAndShutdown(res, 400, authPages.failurePage());
-      callbackReject(new Error('No API key received in callback'));
+      respondAndShutdown(res, 400, authPages.failurePage(reason));
+      callbackReject(new Error(reason || 'No API key received in callback'));
       return;
     }
 
@@ -116,7 +139,7 @@ async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
     config.writeConfig(cfg);
 
     respondAndShutdown(res, 200, authPages.successPage({ email, orgName }));
-    callbackResolve({ email, orgName });
+    callbackResolve(grantedScope ? { email, orgName, scope: grantedScope } : { email, orgName });
   });
 
   await new Promise((resolve, reject) => {
@@ -125,8 +148,11 @@ async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
   });
 
   const port = server.address().port;
-  const callbackUrl = `http://localhost:${port}/callback`;
-  const authUrl = `${frontendUrl}/automations/api-key-callback?callback_url=${encodeURIComponent(callbackUrl)}&app_type=cli`;
+  // 127.0.0.1 literal: the server binds only IPv4, so a `localhost` redirect could land on a squatter at [::1].
+  const callbackUrl = `http://127.0.0.1:${port}/callback?state=${state}`;
+  // `machine` names the login token after this host, so a re-login replaces that token instead of adding one.
+  const params = new URLSearchParams({ callback_url: callbackUrl, app_type: 'cli', machine: os.hostname(), ...scope });
+  const authUrl = `${frontendUrl}/automations/api-key-callback?${params.toString()}`;
 
   const open = openFn || (await import('open')).default;
 

package/src/commands/login.js

@@ -4,6 +4,7 @@ const output = require('../output');
 const api = require('../api');
 const { loginWithBrowser, loginWithApiKey, fetchDeviceKey } = require('../auth');
 const { getDeviceSerial } = require('../device-serial');
+const { parseLoginScope, isScoped, describeToken } = require('../login-scope');
 
 function register(program) {
   program
@@ -15,6 +16,9 @@ function register(program) {
     .option('--backend-url <url>', 'Tenant backend REST API URL (e.g. https://backend.acme.com). Persisted to config.')
     .addOption(new Option('--base-url <url>', 'Hidden alias of --backend-url, kept for back-compat.').hideHelp())
     .option('--domain <domain>', 'Use a custom domain for login (e.g. custom.example.com)')
+    .option('--role <name>', 'Browser login only: scope the token to a console role (admin, analytics-viewer, manager, or a custom role name)')
+    .option('--permissions <list>', 'Browser login only: scope the token per area, e.g. analytics=view,logs=view (unlisted areas get none)')
+    .option('--expires-in-days <days>', 'Browser login only: token lifetime, one of 7, 30, 60, 90 (default 90)')
     .addHelpText('after', `
 Authentication methods:
   Browser login (default):
@@ -35,9 +39,17 @@ Options:
   --domain sets a custom domain for organizations with self-hosted frontends.
   Bare hostnames (e.g. "api.acme.com") are auto-prefixed with https://.
 
+Scoped browser login (--role / --permissions / --expires-in-days):
+  By default the login token has your full access for 90 days. Scope it to a
+  console role or to specific areas; the dashboard still caps it to your own
+  access. Re-running login on this machine replaces its previous token.
+
 Examples:
   $ unbound login                              # Login via default gateway
   $ unbound login --api-key sk-abc123          # Non-interactive login
+  $ unbound login --role analytics-viewer      # View-only token
+  $ unbound login --role "Policy Auditor" --expires-in-days 30
+  $ unbound login --permissions analytics=view,logs=view
   $ unbound login --api-key sk-abc123 \\
       --gateway-url https://api.acme.com \\
       --frontend-url https://gateway.acme.com \\
@@ -60,8 +72,12 @@ Examples:
         // wrong tenant.
         const explicitBaseUrl = written.base_url;
         const explicitFrontendUrl = written.frontend_url;
+        const scope = parseLoginScope(opts);
 
         if (opts.apiKey) {
+          if (isScoped(scope)) {
+            output.warn('--role, --permissions and --expires-in-days apply to browser login only; the given key is used as is.');
+          }
           try {
             await loginWithApiKey(opts.apiKey, { baseUrl: explicitBaseUrl });
           } catch {
@@ -77,14 +93,20 @@ Examples:
           } else {
             frontendUrl = explicitFrontendUrl || config.getFrontendUrl();
           }
-          await loginWithBrowser(frontendUrl);
+          const result = await loginWithBrowser(frontendUrl, { scope });
+          if (isScoped(scope) && !result.scope) {
+            output.warn('Dashboard ignored your login flags. Stored a default 90-day full-access token. '
+              + 'Revoke it under Settings › API Tokens if unwanted.');
+          }
           // Validate the just-stored key against the explicit backend if one
           // was just persisted; otherwise fall back to the env-var-aware
           // getter. api.get reads the stored key from config internally.
           const deviceSerial = await getDeviceSerial();
-          await api.get('/api/v1/users/privileges/', {
+          const privileges = await api.get('/api/v1/users/privileges/', {
             baseUrl: explicitBaseUrl, query: { device_serial: deviceSerial },
           });
+          const token = describeToken(privileges);
+          if (token) output.info(`Token: ${token}`);
           // Replace whatever config.json held (an old CLI login, another org's key) with this login's device key.
           try {
             config.setDeviceKey(await fetchDeviceKey(config.getApiKey(), { baseUrl: explicitBaseUrl }));

package/src/commands/status.js

@@ -4,9 +4,12 @@ const output = require('../output');
 const { getDeviceSerial } = require('../device-serial');
 const { detectTools, validateToolKeys, countValidationSkipped } = require('../toolHealth');
 const claudePaths = require('../claudePaths');
+const { describeToken } = require('../login-scope');
 
 function roleFromPrivileges(p) {
   if (!p) return null;
+  // A scoped token reports its own cap, not the owner's role flags.
+  if (p.cli_token && p.cli_token.permissions) return 'Scoped token';
   if (p.is_admin) return 'Admin';
   if (p.is_analytics_viewer) return 'Analytics Viewer';
   if (p.is_manager) return 'Manager';
@@ -25,7 +28,8 @@ Output fields:
   Logged in        - Whether credentials are stored (Yes/No)
   Email            - The authenticated user's email (if logged in)
   Organization     - The organization name (if logged in)
-  Role             - Admin / Analytics Viewer / Manager / Member (if logged in)
+  Role             - Admin / Analytics Viewer / Manager / Member, or "Scoped token" (if logged in)
+  Token            - Login token name, scope and expiry (if signed in with a CLI token)
   Backend URL      - REST API host (configurable for tenant deployments)
   Frontend URL     - Browser login host
   Gateway URL      - AI gateway host (used by tool setup)
@@ -51,6 +55,7 @@ Examples:
 
         let connectivity = 'Not checked (not logged in)';
         let role = null;
+        let token = null;
         if (loggedIn) {
           const spin = output.spinner('Checking API connectivity...');
           try {
@@ -60,6 +65,7 @@ Examples:
             });
             config.backfillUserInfo(privileges);
             role = roleFromPrivileges(privileges);
+            token = describeToken(privileges);
             spin.stop();
             connectivity = 'Connected';
           } catch (err) {
@@ -71,6 +77,7 @@ Examples:
           pairs.push(['Email', cfg.email || '-']);
           pairs.push(['Organization', cfg.org_name || '-']);
           pairs.push(['Role', role || '-']);
+          if (token) pairs.push(['Token', token]);
         }
         pairs.push(['Backend URL', config.getBaseUrl()]);
         pairs.push(['Frontend URL', config.getFrontendUrl()]);
@@ -100,6 +107,7 @@ Examples:
             email: loggedIn ? (cfg.email || null) : null,
             organization: loggedIn ? (cfg.org_name || null) : null,
             role: role,
+            token: token,
             backend_url: config.getBaseUrl(),
             frontend_url: config.getFrontendUrl(),
             gateway_url: config.getGatewayUrl(),

package/src/index.js

@@ -38,6 +38,7 @@ AUTHENTICATION
   $ unbound login                          Sign in via browser
   $ unbound login --api-key <key>          Sign in with an API key (for CI/CD)
   $ unbound login --domain custom.co       Sign in via custom domain
+  $ unbound login --role analytics-viewer  Browser sign-in with a view-only token
   $ unbound logout                         Remove stored credentials
   $ unbound status                         Show CLI status, role, and connected tools
   $ unbound doctor                         Diagnose per-tool health and API key

package/src/login-scope.js

@@ -0,0 +1,85 @@
+/**
+ * Scope flags for `unbound login`: what the minted login token may do and for how long.
+ * Parsed before the browser opens so a typo fails here, not after the round trip.
+ */
+const AREAS = ['analytics', 'logs', 'policies', 'configuration'];
+const LEVELS = ['none', 'view', 'edit'];
+const EXPIRY_DAYS = [7, 30, 60, 90];
+const ROLE_NAME_MAX_LENGTH = 64;
+
+// Built-in roles by their shell-friendly slug; custom role names pass through verbatim.
+const BUILTIN_ROLE_SLUGS = {
+  admin: 'Admin',
+  'analytics-viewer': 'Analytics Viewer',
+  manager: 'Manager',
+  member: 'Member',
+};
+
+const AREA_LABELS = { analytics: 'Analytics', logs: 'Logs', policies: 'Policies', configuration: 'Configuration' };
+
+function parsePermissions(raw) {
+  const permissions = Object.fromEntries(AREAS.map((area) => [area, 'none']));
+  for (const pair of String(raw).split(',')) {
+    const parts = pair.trim().split('=');
+    const [area, level] = parts;
+    if (parts.length !== 2 || !area || !level) throw new Error(`Invalid permissions entry "${pair.trim()}". Use area=level, e.g. analytics=view`);
+    if (!AREAS.includes(area)) throw new Error(`Unknown area "${area}". Areas: ${AREAS.join(', ')}`);
+    if (!LEVELS.includes(level)) throw new Error(`Unknown level "${level}" for ${area}. Levels: ${LEVELS.join(', ')}`);
+    if (area === 'logs' && level === 'edit') throw new Error('Logs has no edit level');
+    permissions[area] = level;
+  }
+  return permissions;
+}
+
+/**
+ * Turns the login flags into the query the dashboard reads. Returns {} when no flag was given.
+ * @param {{role?: string, permissions?: string, expiresInDays?: string|number}} opts
+ */
+function parseLoginScope(opts = {}) {
+  const query = {};
+  const role = typeof opts.role === 'string' ? opts.role.trim() : '';
+  const permissions = typeof opts.permissions === 'string' ? opts.permissions.trim() : '';
+  if (opts.role !== undefined && !role) throw new Error('--role must not be empty');
+  if (opts.permissions !== undefined && !permissions) throw new Error('--permissions must not be empty');
+  if (role && permissions) throw new Error('Use --role or --permissions, not both');
+  if (opts.expiresInDays !== undefined) {
+    const days = Number(opts.expiresInDays);
+    if (!EXPIRY_DAYS.includes(days)) throw new Error(`--expires-in-days must be one of ${EXPIRY_DAYS.join(', ')}`);
+    query.expires_in_days = String(days);
+  }
+  if (role) {
+    const slug = role.toLowerCase();
+    const name = Object.hasOwn(BUILTIN_ROLE_SLUGS, slug) ? BUILTIN_ROLE_SLUGS[slug] : role;
+    if (name.length > ROLE_NAME_MAX_LENGTH) throw new Error(`Unknown role "${role}"`);
+    query.role = name;
+  } else if (permissions) {
+    const map = parsePermissions(permissions);
+    query.permissions = AREAS.filter((a) => map[a] !== 'none').map((a) => `${a}=${map[a]}`).join(',');
+    if (!query.permissions) throw new Error('--permissions grants no access');
+  }
+  return query;
+}
+
+/** True when any login flag was given, so a dashboard that echoes no `scope` must have ignored it. */
+function isScoped(query) {
+  return Object.keys(query).length > 0;
+}
+
+/** "Analytics view, Logs view" from a permissions map, or "full access" for null. */
+function formatPermissions(permissions) {
+  if (!permissions || typeof permissions !== 'object') return 'full access';
+  const granted = AREAS.filter((a) => permissions[a] && permissions[a] !== 'none')
+    .map((a) => `${AREA_LABELS[a]} ${permissions[a]}`);
+  return granted.length ? granted.join(', ') : 'no access';
+}
+
+/** One line describing the token the privileges call reports, or null when the caller is not a CLI token. */
+function describeToken(privileges) {
+  const token = privileges && privileges.cli_token;
+  if (!token || typeof token !== 'object') return null;
+  const parts = [token.name, formatPermissions(token.permissions)];
+  if (token.expires_at) parts.push(`expires ${String(token.expires_at).slice(0, 10)}`);
+  return parts.filter(Boolean).join(' · ');
+}
+
+module.exports = { parseLoginScope, isScoped, formatPermissions, describeToken, BUILTIN_ROLE_SLUGS, EXPIRY_DAYS };

package/test/auth-server-leak.test.js

@@ -1,6 +1,7 @@
 const { test } = require('node:test');
 const assert = require('node:assert/strict');
 const http = require('http');
+const os = require('os');
 const { URL } = require('url');
 
 // WEB-4941, root cause #1: loginWithBrowser's local callback server leaked a
@@ -63,11 +64,17 @@ function expectConnectionRefused(port) {
   });
 }
 
-// Pulls the callback_url the server told the browser to redirect to, then
-// appends the success params the /callback handler reads (api_key/email/org).
+// Mirrors the dashboard: keep callback_url's own query (the state nonce) and
+// set the success params the /callback handler reads (api_key/email/org).
+function withCallbackParams(callbackUrl, params) {
+  const u = new URL(callbackUrl);
+  for (const [k, v] of Object.entries(params)) u.searchParams.set(k, v);
+  return u.toString();
+}
+
 function buildSuccessCallback(authUrl) {
   const callbackUrl = new URL(authUrl).searchParams.get('callback_url');
-  return `${callbackUrl}?api_key=sk-test&email=a@b.co&org=Acme`;
+  return withCallbackParams(callbackUrl, { api_key: 'sk-test', email: 'a@b.co', org: 'Acme' });
 }
 
 // Monkeypatch config so no real ~/.unbound write happens. Restored in finally.
@@ -105,8 +112,11 @@ test('loginWithBrowser: success path resolves, sets Connection: close, and stops
     let successHeaders;
     let successSocket;
 
+    let authParams;
+
     const fakeOpen = async (authUrl) => {
-      port = Number(new URL(new URL(authUrl).searchParams.get('callback_url')).port);
+      authParams = new URL(authUrl).searchParams;
+      port = Number(new URL(authParams.get('callback_url')).port);
       const res = await getKeepAlive(agent, buildSuccessCallback(authUrl));
       successHeaders = res.headers;
       successSocket = res.socket;
@@ -120,6 +130,9 @@ test('loginWithBrowser: success path resolves, sets Connection: close, and stops
       );
 
       assert.deepEqual(result, { email: 'a@b.co', orgName: 'Acme' });
+      // The dashboard names this machine's login token after `machine`, so a re-login replaces it.
+      assert.equal(authParams.get('app_type'), 'cli');
+      assert.equal(authParams.get('machine'), os.hostname());
       assert.equal(successHeaders.connection, 'close', 'success response must set Connection: close');
 
       // The leak-proof: the held keep-alive socket is actually closed by the
@@ -142,13 +155,13 @@ test('loginWithBrowser: duplicate /callback cannot overwrite the stored credenti
 
     const fakeOpen = async (authUrl) => {
       const callbackUrl = new URL(authUrl).searchParams.get('callback_url');
-      await getKeepAlive(agent, `${callbackUrl}?api_key=sk-first&email=a@b.co&org=Acme`);
+      await getKeepAlive(agent, withCallbackParams(callbackUrl, { api_key: 'sk-first', email: 'a@b.co', org: 'Acme' }));
       // Second callback with a different key: teardown is deferred to the
       // response flush, so the server may still be up — it must answer 409
       // without persisting; once down, ECONNREFUSED is equally acceptable.
       // Either way the first credentials must be the only ones stored.
       try {
-        const dup = await getKeepAlive(agent, `${callbackUrl}?api_key=sk-attacker&email=x@y.z&org=Evil`);
+        const dup = await getKeepAlive(agent, withCallbackParams(callbackUrl, { api_key: 'sk-attacker', email: 'x@y.z', org: 'Evil' }));
         assert.equal(dup.statusCode, 409, 'late duplicate must be rejected, not processed');
       } catch (err) {
         if (err.code !== 'ECONNREFUSED') throw err;

package/test/login-scope-callback.test.js

@@ -0,0 +1,211 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const http = require('http');
+const { URL } = require('url');
+
+// The browser round trip for a scoped login: the flags ride on the auth URL, the dashboard's
+// `scope=` echo comes back on success, and its `error=` reason is what the user sees on failure.
+
+const auth = require('../src/auth');
+const config = require('../src/config');
+
+function get(url) {
+  return new Promise((resolve, reject) => {
+    http.get(url, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => resolve({ statusCode: res.statusCode, body }));
+    }).on('error', reject);
+  });
+}
+
+// Mirrors the dashboard: `new URL(callback_url)` keeps the state nonce, then the result params are set on it.
+function withCallbackParams(callbackUrl, params) {
+  const u = new URL(callbackUrl);
+  for (const [k, v] of Object.entries(params)) u.searchParams.set(k, v);
+  return u.toString();
+}
+
+function withStubbedConfig(fn) {
+  const saved = { setApiKey: config.setApiKey, writeConfig: config.writeConfig, readConfig: config.readConfig };
+  config.setApiKey = () => {};
+  config.writeConfig = () => {};
+  config.readConfig = () => ({});
+  return Promise.resolve().then(fn).finally(() => Object.assign(config, saved));
+}
+
+test('loginWithBrowser: scope flags ride on the auth URL and the echoed scope comes back', async () => {
+  await withStubbedConfig(async () => {
+    let authParams;
+    const fakeOpen = async (authUrl) => {
+      authParams = new URL(authUrl).searchParams;
+      const callbackUrl = authParams.get('callback_url');
+      setImmediate(() => get(withCallbackParams(callbackUrl, { api_key: 'sk-test', email: 'a@b.co', org: 'Acme', scope: 'role:Analytics Viewer' })));
+    };
+
+    const result = await auth.loginWithBrowser('http://frontend.invalid', {
+      open: fakeOpen, scope: { role: 'Analytics Viewer', expires_in_days: '30' },
+    });
+
+    assert.equal(authParams.get('role'), 'Analytics Viewer');
+    assert.equal(authParams.get('expires_in_days'), '30');
+    assert.equal(authParams.get('app_type'), 'cli');
+    assert.deepEqual(result, { email: 'a@b.co', orgName: 'Acme', scope: 'role:Analytics Viewer' });
+  });
+});
+
+test('loginWithBrowser: control characters in the callback error never reach the terminal', async () => {
+  await withStubbedConfig(async () => {
+    const fakeOpen = async (authUrl) => {
+      const callbackUrl = new URL(authUrl).searchParams.get('callback_url');
+      setImmediate(() => get(withCallbackParams(callbackUrl, { error: 'bad\u001b[31m role\u0007' })));
+    };
+    await assert.rejects(
+      () => auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen, scope: { role: 'x' } }),
+      (err) => err.message === 'bad[31m role',
+    );
+  });
+});
+
+test('loginWithBrowser: the dashboard\'s error reason is the rejection and shows on the failure page', async () => {
+  await withStubbedConfig(async () => {
+    let page;
+    const fakeOpen = async (authUrl) => {
+      const callbackUrl = new URL(authUrl).searchParams.get('callback_url');
+      setImmediate(async () => { page = await get(withCallbackParams(callbackUrl, { error: 'Unknown role "Policy-Auditor"' })); });
+    };
+
+    await assert.rejects(
+      () => auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen, scope: { role: 'Policy-Auditor' } }),
+      /Unknown role "Policy-Auditor"/,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    assert.equal(page.statusCode, 400);
+    assert.match(page.body, /Unknown role "Policy-Auditor"/);
+  });
+});
+
+// WEB-6462: the callback is gated by a per-login `state` nonce and pinned to 127.0.0.1, so a local
+// page or an IPv6 bind-squatter can neither complete the login nor read the dashboard's redirect.
+
+function sleep(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }
+
+test('loginWithBrowser: callback_url is pinned to 127.0.0.1 and carries a 32-hex state nonce', async () => {
+  await withStubbedConfig(async () => {
+    let callbackUrl;
+    const fakeOpen = async (authUrl) => {
+      callbackUrl = new URL(new URL(authUrl).searchParams.get('callback_url'));
+      setImmediate(() => get(withCallbackParams(callbackUrl, { api_key: 'sk-test' })));
+    };
+    await auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen });
+    assert.equal(callbackUrl.hostname, '127.0.0.1');
+    assert.equal(callbackUrl.pathname, '/callback');
+    assert.match(callbackUrl.searchParams.get('state'), /^[0-9a-f]{32}$/);
+  });
+});
+
+test('loginWithBrowser: a wrong state gets 400 and the real callback still completes with 200', async () => {
+  await withStubbedConfig(async () => {
+    const storedKeys = [];
+    config.setApiKey = (key) => { storedKeys.push(key); };
+    let forged;
+    let real;
+    const fakeOpen = async (authUrl) => {
+      const callbackUrl = new URL(authUrl).searchParams.get('callback_url');
+      setImmediate(async () => {
+        forged = await get(withCallbackParams(callbackUrl, { state: 'f'.repeat(32), api_key: 'sk-attacker' }));
+        // The login settles before this response body flushes, so hold the promise and await it below.
+        real = get(withCallbackParams(callbackUrl, { api_key: 'sk-real', email: 'a@b.co', org: 'Acme' }));
+      });
+    };
+    const result = await auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen });
+    assert.equal(forged.statusCode, 400);
+    assert.equal((await real).statusCode, 200, 'the forged request must not consume the one-shot callback');
+    assert.deepEqual(result, { email: 'a@b.co', orgName: 'Acme' });
+    assert.deepEqual(storedKeys, ['sk-real']);
+  });
+});
+
+test('loginWithBrowser: a callback without state gets 400 and the login still completes', async () => {
+  await withStubbedConfig(async () => {
+    let bare;
+    const fakeOpen = async (authUrl) => {
+      const callbackUrl = new URL(new URL(authUrl).searchParams.get('callback_url'));
+      const noState = new URL(callbackUrl); noState.searchParams.delete('state'); noState.searchParams.set('api_key', 'sk-attacker');
+      setImmediate(async () => {
+        bare = await get(noState.toString());
+        await get(withCallbackParams(callbackUrl, { api_key: 'sk-real', email: 'a@b.co', org: 'Acme' }));
+      });
+    };
+    const result = await auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen });
+    assert.equal(bare.statusCode, 400);
+    assert.deepEqual(result, { email: 'a@b.co', orgName: 'Acme' });
+  });
+});
+
+test('loginWithBrowser: a wrong-state error= neither shows its text nor settles the login', async () => {
+  await withStubbedConfig(async () => {
+    let forged;
+    let callbackUrl;
+    const fakeOpen = async (authUrl) => {
+      callbackUrl = new URL(authUrl).searchParams.get('callback_url');
+      setImmediate(async () => {
+        forged = await get(withCallbackParams(callbackUrl, { state: '0'.repeat(32), error: 'ATTACKER-TEXT' }));
+      });
+    };
+    let settled = false;
+    const login = auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen }).finally(() => { settled = true; });
+    await sleep(100);
+    assert.equal(forged.statusCode, 400);
+    assert.doesNotMatch(forged.body, /ATTACKER-TEXT/);
+    assert.equal(settled, false, 'a forged error must not reject the login');
+    // Finish the login so the server does not outlive the test.
+    await get(withCallbackParams(callbackUrl, { api_key: 'sk-real' }));
+    await login;
+  });
+});
+
+test('loginWithBrowser: a 32-char multi-byte state gets 400 instead of crashing the server', async () => {
+  await withStubbedConfig(async () => {
+    let forged;
+    const fakeOpen = async (authUrl) => {
+      const callbackUrl = new URL(authUrl).searchParams.get('callback_url');
+      setImmediate(async () => {
+        // Same JS length as the real nonce, different UTF-8 byte length.
+        forged = await get(withCallbackParams(callbackUrl, { state: '\u00e9'.repeat(32), api_key: 'sk-attacker' }));
+        await get(withCallbackParams(callbackUrl, { api_key: 'sk-real', email: 'a@b.co', org: 'Acme' }));
+      });
+    };
+    const result = await auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen });
+    assert.equal(forged.statusCode, 400);
+    assert.deepEqual(result, { email: 'a@b.co', orgName: 'Acme' });
+  });
+});
+
+test('loginWithBrowser: each login mints a different state', async () => {
+  await withStubbedConfig(async () => {
+    const states = [];
+    const fakeOpen = async (authUrl) => {
+      const callbackUrl = new URL(authUrl).searchParams.get('callback_url');
+      states.push(new URL(callbackUrl).searchParams.get('state'));
+      setImmediate(() => get(withCallbackParams(callbackUrl, { api_key: 'sk-test' })));
+    };
+    await auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen });
+    await auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen });
+    assert.equal(states.length, 2);
+    assert.notEqual(states[0], states[1]);
+  });
+});
+
+test('loginWithBrowser: error= with the correct state still rejects with the dashboard reason', async () => {
+  await withStubbedConfig(async () => {
+    const fakeOpen = async (authUrl) => {
+      const callbackUrl = new URL(authUrl).searchParams.get('callback_url');
+      setImmediate(() => get(withCallbackParams(callbackUrl, { error: 'Role not permitted' })));
+    };
+    await assert.rejects(
+      () => auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen }),
+      /Role not permitted/,
+    );
+  });
+});

package/test/login-scope.test.js

@@ -0,0 +1,51 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { parseLoginScope, isScoped, formatPermissions, describeToken } = require('../src/login-scope');
+
+test('parseLoginScope: no flags means a plain login', () => {
+  assert.deepEqual(parseLoginScope({}), {});
+  assert.equal(isScoped({}), false);
+});
+
+test('parseLoginScope: a flag given but empty is an error, not a plain login', () => {
+  assert.throws(() => parseLoginScope({ role: ' ' }), /--role must not be empty/);
+  assert.throws(() => parseLoginScope({ permissions: '' }), /--permissions must not be empty/);
+  assert.equal(isScoped(parseLoginScope({ expiresInDays: '7' })), true);
+});
+
+test('parseLoginScope: built-in slugs map to the role name, custom names pass verbatim', () => {
+  assert.deepEqual(parseLoginScope({ role: 'analytics-viewer' }), { role: 'Analytics Viewer' });
+  assert.deepEqual(parseLoginScope({ role: 'ADMIN' }), { role: 'Admin' });
+  assert.deepEqual(parseLoginScope({ role: ' Policy Auditor ' }), { role: 'Policy Auditor' });
+  assert.deepEqual(parseLoginScope({ role: 'constructor' }), { role: 'constructor' });
+  assert.deepEqual(parseLoginScope({ role: '__proto__' }), { role: '__proto__' });
+});
+
+test('parseLoginScope: permissions keep only granted areas, in a fixed order', () => {
+  assert.deepEqual(
+    parseLoginScope({ permissions: 'logs=view, analytics=view', expiresInDays: '30' }),
+    { expires_in_days: '30', permissions: 'analytics=view,logs=view' },
+  );
+});
+
+test('parseLoginScope: rejects bad input before the browser opens', () => {
+  assert.throws(() => parseLoginScope({ role: 'admin', permissions: 'analytics=view' }), /not both/);
+  assert.throws(() => parseLoginScope({ expiresInDays: '45' }), /7, 30, 60, 90/);
+  assert.throws(() => parseLoginScope({ permissions: 'foo=view' }), /Unknown area "foo"/);
+  assert.throws(() => parseLoginScope({ permissions: 'analytics=admin' }), /Unknown level "admin"/);
+  assert.throws(() => parseLoginScope({ permissions: 'logs=edit' }), /no edit level/);
+  assert.throws(() => parseLoginScope({ permissions: 'analytics' }), /area=level/);
+  assert.throws(() => parseLoginScope({ permissions: 'analytics=none' }), /grants no access/);
+  assert.throws(() => parseLoginScope({ role: 'x'.repeat(65) }), /Unknown role/);
+});
+
+test('formatPermissions and describeToken read the privileges payload', () => {
+  assert.equal(formatPermissions(null), 'full access');
+  assert.equal(formatPermissions({ analytics: 'view', logs: 'view', policies: 'none', configuration: 'none' }), 'Analytics view, Logs view');
+  assert.equal(describeToken({ is_admin: true }), null);
+  assert.equal(
+    describeToken({ cli_token: { name: 'cli-login:mbp', permissions: null, expires_at: '2027-02-01T00:00:00Z' } }),
+    'cli-login:mbp · full access · expires 2027-02-01',
+  );
+});