unbound-cli 1.9.0 → 1.11.0

package/package.json

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

package/src/auth-pages.js

@@ -0,0 +1,178 @@
+/**
+ * HTML pages served by the local auth-callback server (src/auth.js).
+ *
+ * Design follows the unbound-fe light-surface language (matching the auth
+ * login page): #fafafb scene with a soft purple glow, white card on a gray-200
+ * border, #3d3d3d headings, brand purple #7B56FB (logo) accents, Inter-first
+ * font stack. Fully self-contained —
+ * no external fonts, scripts, or images — so the page renders identically
+ * offline and never blocks on a network fetch from a localhost one-shot server.
+ *
+ * SECURITY: email/org arrive as query params on a loopback URL anyone local
+ * can hit, so every interpolated value MUST go through escapeHtml. Never
+ * interpolate the api_key into a page.
+ */
+
+/** Minimal HTML entity escape for untrusted interpolated text. */
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+// Unbound shield mark (public/Unbound.svg in unbound-fe), inlined verbatim.
+const LOGO_SVG =
+  '<svg width="28" height="27" viewBox="0 0 24 23" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">' +
+  '<path d="M5.12736 6.88525C6.33833 14.4266 11.9473 18.6338 12.0038 18.6757L9.577 22.0419C9.28788 21.8335 2.47374 16.8456 0.979492 7.53649L5.12639 6.88525H5.12736Z" fill="#7B56FB"/>' +
+  '<path d="M18.7655 6.81787L22.8988 7.24132C22.8637 7.59566 21.9496 15.9907 14.6361 21.9394L12.0059 18.6755C17.9322 13.8559 18.7577 6.88796 18.7655 6.81787Z" fill="#7B56FB"/>' +
+  '<path d="M12.1878 1.4375C14.6214 1.4375 17.3928 1.8113 20.282 2.91325L18.7654 6.81775C11.5638 4.07068 5.19258 6.85572 5.12833 6.88492L3.42188 3.10697C3.63993 3.00865 7.20178 1.4375 12.1878 1.4375Z" fill="#7B56FB"/>' +
+  '</svg>';
+
+/**
+ * Shared page shell. `status` slots the icon block, heading, and body copy;
+ * `accent` tints the icon ring (brand purple on success, red on failure).
+ */
+function renderPage({ title, icon, heading, body }) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    background: #fafafb;
+    min-height: 100vh;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 24px;
+    /* Soft brand glow behind the card, echoing the light auth/login scene. */
+    background-image: radial-gradient(600px 400px at 50% 30%, rgba(123, 86, 251, 0.07), transparent 70%);
+  }
+  .card {
+    background: #ffffff;
+    border: 1px solid #e5e7eb;
+    border-radius: 16px;
+    padding: 44px 40px 36px;
+    max-width: 400px;
+    width: 100%;
+    text-align: center;
+    box-shadow: 0 16px 48px rgba(23, 19, 43, 0.08);
+    animation: rise 0.45s ease-out both;
+  }
+  .brand {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    margin-bottom: 28px;
+  }
+  .brand span {
+    color: #17132B;
+    font-size: 17px;
+    font-weight: 600;
+    letter-spacing: 0.02em;
+  }
+  .icon {
+    display: block;
+    width: 64px;
+    height: 64px;
+    margin: 0 auto 20px;
+  }
+  .icon circle {
+    stroke-dasharray: 166;
+    stroke-dashoffset: 166;
+    animation: draw 0.6s 0.15s ease-out forwards;
+  }
+  .icon .mark {
+    stroke-dasharray: 48;
+    stroke-dashoffset: 48;
+    animation: draw 0.35s 0.65s ease-out forwards;
+  }
+  h1 { color: #3d3d3d; font-size: 20px; font-weight: 600; margin-bottom: 10px; }
+  p { color: #6b7280; font-size: 14px; line-height: 1.6; }
+  .identity {
+    display: inline-flex;
+    flex-direction: column;
+    gap: 2px;
+    margin: 14px 0 6px;
+    padding: 9px 18px;
+    border: 1px solid #e5e7eb;
+    border-radius: 12px;
+    background: #fafafb;
+    font-size: 13px;
+    max-width: 100%;
+    overflow-wrap: anywhere;
+  }
+  .identity b { color: #3d3d3d; font-weight: 500; }
+  .identity i { color: #6b7280; font-style: normal; font-size: 12px; }
+  @keyframes rise { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: none; } }
+  @keyframes draw { to { stroke-dashoffset: 0; } }
+  @media (prefers-reduced-motion: reduce) {
+    .card, .icon circle, .icon .mark { animation: none; stroke-dashoffset: 0; }
+  }
+</style>
+</head>
+<body>
+<main class="card">
+  <div class="brand">${LOGO_SVG}<span>unbound</span></div>
+  ${icon}
+  <h1>${heading}</h1>
+  ${body}
+</main>
+</body>
+</html>
+`;
+}
+
+// Stroke-drawn status icons: circle sweeps in first, then the mark.
+const CHECK_ICON =
+  '<svg class="icon" viewBox="0 0 56 56" fill="none" aria-hidden="true">' +
+  '<circle cx="28" cy="28" r="26" stroke="#7B56FB" stroke-width="2.5"/>' +
+  '<path class="mark" d="M17 29l8 8 14-16" stroke="#7B56FB" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>' +
+  '</svg>';
+
+const CROSS_ICON =
+  '<svg class="icon" viewBox="0 0 56 56" fill="none" aria-hidden="true">' +
+  '<circle cx="28" cy="28" r="26" stroke="#EF4444" stroke-width="2.5"/>' +
+  '<path class="mark" d="M20 20l16 16M36 20L20 36" stroke="#EF4444" stroke-width="3" stroke-linecap="round"/>' +
+  '</svg>';
+
+/**
+ * Success page shown after the API key lands. `email`/`orgName` are untrusted
+ * query-param values — escaped here, and omitted entirely when absent.
+ */
+function successPage({ email, orgName } = {}) {
+  // Stacked (email over org) rather than one truncating line — real tenant
+  // emails and org names routinely overflow a 400px card side by side.
+  const identityParts = [];
+  if (email) identityParts.push(`<b>${escapeHtml(email)}</b>`);
+  if (orgName) identityParts.push(`<i>${escapeHtml(orgName)}</i>`);
+  const identity = identityParts.length
+    ? `<div class="identity">${identityParts.join('')}</div>`
+    : '';
+
+  return renderPage({
+    title: 'Authentication Successful | Unbound',
+    icon: CHECK_ICON,
+    heading: 'Authentication Successful',
+    body: `${identity}<p>You can close this tab and return to the terminal.</p>`,
+  });
+}
+
+/** Failure page for a callback that arrived without an api_key. */
+function failurePage() {
+  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>',
+  });
+}
+
+module.exports = { successPage, failurePage, escapeHtml };

package/src/auth.js

@@ -4,6 +4,7 @@
  */
 const http = require('http');
 const { URL } = require('url');
+const authPages = require('./auth-pages');
 const config = require('./config');
 const output = require('./output');
 const api = require('./api');
@@ -35,18 +36,38 @@ async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
   // / timed-out socket so the process exits immediately. closeAllConnections is
   // Node >=18.2 — guard for the package's >=18 engine floor.
   //
-  // Calling this synchronously right after res.end() is safe ONLY because the
-  // callback responses are a few hundred bytes of static HTML — they fit in the
-  // socket send buffer, so the body reaches the kernel before closeAllConnections
-  // destroys the socket. If these pages ever grow to multi-KB (inline assets,
-  // styling), defer teardown to res.on('finish') to avoid truncating the response.
+  // The styled callback pages (auth-pages.js) are multi-KB, so calling this
+  // synchronously after res.end() could destroy the socket before the body
+  // flushes and truncate the page. Callback responses therefore defer teardown
+  // to res 'finish' (body flushed) / 'close' (client vanished mid-write) via
+  // respondAndShutdown; the guard keeps the second event and the timeout path
+  // from double-closing the server (server.close() on a closed server throws).
+  let tornDown = false;
   function shutdownServer() {
+    if (tornDown) return;
+    tornDown = true;
     server.close();
     if (typeof server.closeAllConnections === 'function') {
       server.closeAllConnections();
     }
   }
 
+  // Sends a terminal (success/failure) callback response and tears the server
+  // down once the body has actually left userspace. Resolution of the login
+  // promise stays with the caller — this only owns response + teardown.
+  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.end(html);
+  }
+
+  // First /callback wins. Teardown is deferred until the response body
+  // flushes, which leaves a window where a second /callback could arrive and
+  // overwrite the just-persisted credentials after the login promise has
+  // settled — reject duplicates outright instead of processing them.
+  let callbackHandled = false;
+
   server.on('request', (req, res) => {
     const url = new URL(req.url, `http://localhost`);
 
@@ -56,15 +77,20 @@ async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
       return;
     }
 
+    if (callbackHandled) {
+      res.writeHead(409, { 'Connection': 'close' });
+      res.end('Callback already processed');
+      return;
+    }
+    callbackHandled = true;
+
     const apiKey = url.searchParams.get('api_key');
     const email = url.searchParams.get('email');
     const orgName = url.searchParams.get('org');
 
     if (!apiKey) {
-      res.writeHead(400, { 'Content-Type': 'text/html', 'Connection': 'close' });
-      res.end('<html><body><h2>Authentication failed</h2><p>No API key received. Please try again.</p></body></html>');
+      respondAndShutdown(res, 400, authPages.failurePage());
       callbackReject(new Error('No API key received in callback'));
-      shutdownServer();
       return;
     }
 
@@ -74,11 +100,8 @@ async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
     if (orgName) cfg.org_name = orgName;
     config.writeConfig(cfg);
 
-    res.writeHead(200, { 'Content-Type': 'text/html', 'Connection': 'close' });
-    res.end('<html><body><h2>Authentication successful!</h2><p>You can close this tab and return to the terminal.</p></body></html>');
-
+    respondAndShutdown(res, 200, authPages.successPage({ email, orgName }));
     callbackResolve({ email, orgName });
-    shutdownServer();
   });
 
   await new Promise((resolve, reject) => {

package/src/commands/policy.js

@@ -312,6 +312,34 @@ function parseFieldSpec(spec) {
   return [spec.slice(0, eq), spec.slice(eq + 1)];
 }
 
+// The `custom` command family has no match-against fields — its single condition is
+// the reserved `command` key, matched as ONE pattern against the whole raw command
+// regardless of the classified family. The families metadata reports it with
+// is_custom:true and no fields (mirrors the dashboard), so surface how to author it.
+const CUSTOM_FAMILY_NAME = 'custom';
+const CUSTOM_FAMILY_HINT =
+  "matches ONE pattern against the whole command (exact text, *wildcard*, or regex). " +
+  "Author it with --field command='<pattern>', e.g. --field command='make release-prod'.";
+
+// Indented detail lines shown under a family name in `policy tool families`. Pure so
+// the custom-family guidance is unit-testable. A custom family (is_custom) reports no
+// fields by design, so explain its single whole-command pattern instead of "(no fields)".
+function familyFieldLines(f) {
+  // Custom has no fields by design — return before touching f.fields so its shape is
+  // irrelevant for the custom branch.
+  if (f.is_custom) {
+    return [CUSTOM_FAMILY_HINT];
+  }
+  const fields = Array.isArray(f.fields) ? f.fields : Object.keys(f.fields || {});
+  if (fields.length === 0) {
+    return ['(no fields)'];
+  }
+  return fields.map((field) => {
+    const desc = (f.field_descriptions && f.field_descriptions[field]) || '';
+    return `${field}${desc ? ` — ${desc}` : ''}`;
+  });
+}
+
 // "ANY" is a wildcard across all fields; it can't be ANDed with other conditions.
 // Mirrors the backend rule so the CLI fails fast before the API call. The check is
 // case-insensitive so `--field Any=*`/`--field any=*` are caught too.
@@ -1433,8 +1461,8 @@ Subcommands:
     .option('--prompt <text>', 'Natural-language description; routes through Unbound AI assist. Mutually exclusive with --command-family/--field/--config. Compatible with --name/--description/--action overrides.')
     .option('--no-ai', 'Opt out of the AI-assist guard and use raw classification flags. Mutually exclusive with --prompt.')
     .option('--name <name>', 'Policy name (required unless --prompt is used)')
-    .option('--command-family <family>', 'Command family (e.g. git, filesystem, network). See `policy tool families`.')
-    .option('--field <key=pattern>', 'Match field: <key>=<pattern>. Repeatable — multiple --field are ANDed (all must match), one per field, for a more specific policy. At least one required unless --config is used.', (val, prev = []) => [...prev, val])
+    .option('--command-family <family>', 'Command family (e.g. git, filesystem, network), or `custom` to match one pattern against the whole command. See `policy tool families`.')
+    .option('--field <key=pattern>', 'Match field: <key>=<pattern>. Repeatable — multiple --field are ANDed (all must match), one per field, for a more specific policy. At least one required unless --config is used. For the `custom` family the key is `command`.', (val, prev = []) => [...prev, val])
     .option('--action <action>', `Action to take: ${TOOL_ACTIONS.join(' | ')}`)
     .option('--description <text>', 'Human-readable description')
     .option('--custom-message <text>', 'Message shown to the user when the policy fires. Required when --action is BLOCK or WARN.')
@@ -1466,6 +1494,12 @@ Examples:
       --field operation=push --field branch=main --field remote='*origin*' \\
       --action BLOCK --custom-message "Pushing to main on origin is blocked."
 
+  # 'custom' family: one pattern matched against the WHOLE command (exact / *wildcard* / regex),
+  # regardless of the classified family. The field key is always 'command'.
+  $ unbound policy tool create-terminal --no-ai --name "Block prod release" \\
+      --command-family custom --field command='make release-prod' \\
+      --action BLOCK --custom-message "Prod releases go through CI."
+
 Discover valid command families and their fields: unbound policy tool families
 Learn more: ${DOCS_TOOL}
 `)
@@ -1558,12 +1592,18 @@ Learn more: ${DOCS_TOOL}
           throw new Error('Cannot combine --config with --field.');
         }
 
+        const isCustomFamily = (opts.commandFamily || '').toLowerCase() === CUSTOM_FAMILY_NAME;
+
         let configObj;
         if (opts.config) {
           configObj = parseJsonOrThrow(opts.config);
         } else {
           if (!opts.field || opts.field.length === 0) {
-            throw new Error('At least one --field <key>=<pattern> is required (or use --config).');
+            throw new Error(
+              isCustomFamily
+                ? `The 'custom' family ${CUSTOM_FAMILY_HINT}`
+                : 'At least one --field <key>=<pattern> is required (or use --config).'
+            );
           }
           configObj = {};
           for (const spec of opts.field) {
@@ -1874,14 +1914,8 @@ Learn more: ${DOCS_TOOL}
         for (const f of families) {
           console.log('');
           output.info(f.name);
-          const fields = Array.isArray(f.fields) ? f.fields : Object.keys(f.fields || {});
-          if (fields.length === 0) {
-            console.log('  (no fields)');
-          } else {
-            for (const field of fields) {
-              const desc = (f.field_descriptions && f.field_descriptions[field]) || '';
-              console.log(`  ${field}${desc ? ` — ${desc}` : ''}`);
-            }
+          for (const line of familyFieldLines(f)) {
+            console.log(`  ${line}`);
           }
           if (f.risk_level) console.log(`  risk: ${f.risk_level}`);
         }
@@ -2082,4 +2116,4 @@ Learn more: ${DOCS_POLICIES}
   registerLegacy(policy);
 }
 
-module.exports = { register, assertAnyExclusive };
+module.exports = { register, assertAnyExclusive, familyFieldLines, CUSTOM_FAMILY_HINT };

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

@@ -134,6 +134,42 @@ test('loginWithBrowser: success path resolves, sets Connection: close, and stops
   });
 });
 
+test('loginWithBrowser: duplicate /callback cannot overwrite the stored credentials', async () => {
+  await withStubbedConfig(async () => {
+    const agent = new http.Agent({ keepAlive: true });
+    const storedKeys = [];
+    config.setApiKey = (key) => { storedKeys.push(key); };
+
+    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`);
+      // 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`);
+        assert.equal(dup.statusCode, 409, 'late duplicate must be rejected, not processed');
+      } catch (err) {
+        if (err.code !== 'ECONNREFUSED') throw err;
+      }
+    };
+
+    try {
+      const result = await withTimeout(
+        auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen }),
+        10_000,
+        'loginWithBrowser duplicate-callback path',
+      );
+
+      assert.deepEqual(result, { email: 'a@b.co', orgName: 'Acme' });
+      assert.deepEqual(storedKeys, ['sk-first'], 'only the first callback may persist credentials');
+    } finally {
+      agent.destroy();
+    }
+  });
+});
+
 test('loginWithBrowser: 404 path also sets Connection: close', async () => {
   await withStubbedConfig(async () => {
     const agent = new http.Agent({ keepAlive: true });

package/test/policy-conditions.test.js

@@ -3,7 +3,7 @@
 const { test } = require('node:test');
 const assert = require('node:assert');
 
-const { assertAnyExclusive } = require('../src/commands/policy');
+const { assertAnyExclusive, familyFieldLines, CUSTOM_FAMILY_HINT } = require('../src/commands/policy');
 
 test('assertAnyExclusive: allows a single ANY condition', () => {
   assert.doesNotThrow(() => assertAnyExclusive({ ANY: '*' }));
@@ -26,3 +26,32 @@ test('assertAnyExclusive: tolerates empty/undefined config', () => {
   assert.doesNotThrow(() => assertAnyExclusive({}));
   assert.doesNotThrow(() => assertAnyExclusive(undefined));
 });
+
+// `policy tool families` must teach an agent how to author a custom policy: the
+// custom family reports is_custom + no fields, and must render the command-pattern
+// hint (not "(no fields)", which reads as "unusable").
+test('familyFieldLines: custom family shows the command-pattern hint, not "(no fields)"', () => {
+  const lines = familyFieldLines({ name: 'custom', is_custom: true, fields: [] });
+  assert.deepStrictEqual(lines, [CUSTOM_FAMILY_HINT]);
+  assert.match(lines[0], /--field command=/);
+  assert.match(lines[0], /exact text, \*wildcard\*, or regex/);
+});
+
+test('familyFieldLines: a normal family with fields lists field — description', () => {
+  const lines = familyFieldLines({
+    name: 'git_action',
+    fields: ['operation', 'branch'],
+    field_descriptions: { operation: 'push/pull/…', branch: 'branch name' },
+  });
+  assert.deepStrictEqual(lines, ['operation — push/pull/…', 'branch — branch name']);
+});
+
+test('familyFieldLines: a fieldless non-custom family still shows "(no fields)"', () => {
+  assert.deepStrictEqual(familyFieldLines({ name: 'misc', fields: [] }), ['(no fields)']);
+});
+
+test('familyFieldLines: custom returns the hint even with no/malformed fields property', () => {
+  // The is_custom guard fires before f.fields is read, so its shape is irrelevant.
+  assert.deepStrictEqual(familyFieldLines({ name: 'custom', is_custom: true }), [CUSTOM_FAMILY_HINT]);
+  assert.deepStrictEqual(familyFieldLines({ is_custom: true, fields: null }), [CUSTOM_FAMILY_HINT]);
+});