unbound-cli 1.18.0 → 1.20.0

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 |
@@ -212,6 +215,66 @@ unbound policy tool delete <id>
 
 Before creating any policy, run `unbound policy form-data` to see available user group names, model names, guardrail names, and existing command policies. The CLI accepts names (e.g. `engg`, `claude-3-opus`, `PII`) and resolves them to backend IDs automatically. You can also pass numeric IDs directly.
 
+### Policy packs as code (Admin only)
+
+Keep policies in versioned YAML files and sync them to your org with `unbound pack`. One file is one **pack**: a named, versioned bundle of one or more policies of kind `tool`, `security`, `model` or `cost`. Every policy in a pack is marked on the server as managed by code, with the pack name and the policy `id` as its identity; its `name` is free text (it defaults to the id). The pack commands match, update and prune only by that identity, so policies made in the console are never read for diffing and never written, whatever they are called.
+
+The console shows a **Managed by Code** badge on those policies and only lets people switch them on or off; every other change goes through the pack file. A policy switched off in the console shows up in `pack diff` as `enabled: false -> true (off on the server, on in the pack)`, and `pack apply` turns it back on (set `enabled: false` in the file to keep it off). `unbound pack adopt` brings a console policy into a pack without renaming it. Needs a backend that stores the code identity (ai-gateway-data 0448 or later).
+
+Docs: https://docs.getunbound.ai/policies/policy-as-code
+
+```yaml
+# policies/k8s-baseline.yaml
+apiVersion: unbound.security/v1
+kind: PolicyPack
+metadata:
+  name: k8s-baseline        # stored on every policy below as its pack identity
+  version: 1.0.0
+defaults:
+  scope:
+    userGroups: [Engineering]
+policies:
+  - id: block-secret-reads
+    kind: tool
+    type: TERMINAL_COMMAND
+    action: BLOCK
+    commandFamily: custom
+    customMessage: Reading cluster secrets is blocked by the k8s-baseline pack.
+    config:
+      command: "regex:kubectl\\s+(get|describe)\\s+secrets?"
+  - id: github-writes-need-approval
+    kind: tool
+    type: MCP_TOOL
+    action: REQUIRE_SLACK_APPROVAL
+    mcp:
+      server: github
+      actionType: write
+  - id: pii-guard
+    kind: security
+    guardrails:
+      - name: PII
+        action: BLOCK
+  - id: monthly-cap
+    kind: cost
+    config:
+      monthly_budget: 5000
+```
+
+```bash
+unbound pack validate -f policies/              # schema check, no server contact
+unbound pack diff -f policies/k8s-baseline.yaml # what apply would change; exit 1 on drift
+unbound pack apply -f policies/k8s-baseline.yaml --dry-run
+unbound pack apply -f policies/k8s-baseline.yaml
+unbound pack apply -f policies/ --prune         # also delete managed policies missing from the files
+unbound pack sync policies/ --yes               # folder is the source of truth (apply + prune)
+unbound pack export k8s-baseline -o policies/k8s-baseline.yaml
+unbound pack export --all -o policies/          # one file per pack found in the org
+unbound pack adopt k8s-baseline --from "Block kubectl secrets" -o policies/k8s-baseline.yaml   # mark a console policy as managed by the pack; its name stays
+unbound pack delete k8s-baseline --yes          # remove every policy the pack manages
+```
+
+User groups, guardrails, models, labels and MCP servers are written by name and resolved at apply time; a name that does not resolve fails before anything is written. `config` is passed to the server as-is. Updates send only the fields that differ, and re-running the same file is safe. `diff` and `--dry-run` never write. A removed pack file does not delete its policies (use `pack delete`), because the server keeps no record of applied packs yet.
+
 ### Users
 
 | Command | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "CLI tool for Unbound - AI Gateway management",
   "main": "src/index.js",
   "bin": {
@@ -23,7 +23,8 @@
     "@iarna/toml": "^2.2.5",
     "@sentry/node": "^10.59.0",
     "commander": "^12.1.0",
-    "open": "^10.1.0"
+    "open": "^10.1.0",
+    "yaml": "^2.9.1"
   },
   "engines": {
     "node": ">=18.0.0"

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

@@ -3,6 +3,7 @@
  * Used by both `login` and `setup` commands.
  */
 const http = require('http');
+const os = require('os');
 const { URL } = require('url');
 const authPages = require('./auth-pages');
 const config = require('./config');
@@ -32,7 +33,7 @@ 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();
   let callbackResolve;
   let callbackReject;
@@ -102,10 +103,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');
+    // The callback is reachable by any local page, so its text is stripped of control characters before display.
+    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 +121,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) => {
@@ -126,7 +131,9 @@ 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`;
+  // `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 }));