@alter-ai/cli 0.3.2 → 0.3.3

package/dist/cli.js

@@ -173,7 +173,7 @@ async function maybePrintUpdateBanner(currentVersion, argv2 = process.argv.slice
 // package.json
 var package_default = {
   name: "@alter-ai/cli",
-  version: "0.3.2",
+  version: "0.3.3",
   description: "Command-line interface for the Alter Vault dev portal \u2014 scripted dashboard automation.",
   type: "module",
   bin: {
@@ -216,7 +216,7 @@ var package_default = {
     tsup: "^8.0.0",
     tsx: "^4.7.0",
     typescript: "^5.5.0",
-    vitest: "^3.0.0"
+    vitest: "^4.1.8"
   },
   engines: {
     node: ">=20.10.0"
@@ -224,7 +224,7 @@ var package_default = {
 };
 
 // src/program.ts
-import { Command as Command14 } from "commander";
+import { Command as Command15 } from "commander";
 
 // src/commands/agents.ts
 import { Command } from "commander";
@@ -1019,6 +1019,45 @@ var ConnectSession = class {
     return `ConnectSession(url=${this.connectUrl}, expires_in=${this.expiresIn})`;
   }
 };
+var AuthSession = class {
+  sessionToken;
+  authUrl;
+  expiresIn;
+  expiresAt;
+  constructor(data) {
+    _assertString(data.session_token, "session_token", "AuthSession");
+    _assertString(data.auth_url, "auth_url", "AuthSession");
+    _assertString(data.expires_at, "expires_at", "AuthSession");
+    if (typeof data.expires_in !== "number" || !Number.isFinite(data.expires_in)) {
+      throw new BackendError("AuthSession: 'expires_in' must be a finite number", {
+        field: "expires_in"
+      });
+    }
+    this.sessionToken = data.session_token;
+    this.authUrl = data.auth_url;
+    this.expiresIn = data.expires_in;
+    this.expiresAt = data.expires_at;
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      session_token: this.sessionToken,
+      auth_url: this.authUrl,
+      expires_in: this.expiresIn,
+      expires_at: this.expiresAt
+    };
+  }
+  toString() {
+    return `AuthSession(authUrl=<redacted>, expiresIn=${this.expiresIn}, expiresAt=${JSON.stringify(this.expiresAt)})`;
+  }
+  /**
+   * Custom Node.js inspect output — redacts authUrl/sessionToken so
+   * console.log / util.inspect can't leak them (mirrors TokenResponse).
+   */
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toString();
+  }
+};
 var ManagedSecretConnectSession = class {
   sessionToken;
   connectUrl;
@@ -1318,7 +1357,8 @@ var AuthResult = class {
   userInfo;
   constructor(data) {
     this.userToken = data.user_token;
-    this.userInfo = data.user_info ?? {};
+    const ui = data.user_info;
+    this.userInfo = typeof ui === "object" && ui !== null && !Array.isArray(ui) ? ui : {};
     Object.freeze(this);
   }
   toJSON() {
@@ -1331,6 +1371,17 @@ var AuthResult = class {
     const sub = this.userInfo?.sub ?? "unknown";
     return `AuthResult(sub=${sub})`;
   }
+  /**
+   * Custom Node.js inspect output — redacts the live IDP JWT `userToken` so
+   * console.log / util.inspect can't leak it (mirrors TokenResponse and the
+   * sibling AuthSession). Without this, util.inspect enumerates own fields and
+   * prints the full bearer token. The Python sibling's `__repr__`/`__str__`
+   * redacts the same field — keep parity, and uphold "NEVER expose tokens in
+   * logs".
+   */
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toString();
+  }
 };
 var SENSITIVE_HEADERS = /* @__PURE__ */ new Set([
   "authorization",
@@ -2940,8 +2991,11 @@ function _extractAdditionalCredentials(token) {
   return _additionalCredsStore.get(token);
 }
 var _fetch;
-var SDK_VERSION = "0.15.0";
+var SDK_VERSION = "0.16.0";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
+var AUTH_POLL_SERVER_WAIT_MS = 25e3;
+var AUTH_POLL_HTTP_BUFFER_MS = 15e3;
+var PERMANENT_POLL_STATUSES = /* @__PURE__ */ new Set([400, 401, 403, 404, 422]);
 var HTTP_FORBIDDEN = 403;
 var HTTP_NO_CONTENT2 = 204;
 var HTTP_NOT_FOUND = 404;
@@ -3068,10 +3122,11 @@ var HttpClient = class {
       ...this.#defaultHeaders,
       ...options?.headers
     };
+    const effectiveTimeoutMs = options?.timeoutMs ?? this.#timeoutMs;
     const controller = new AbortController();
     const timeoutId = setTimeout(() => {
       controller.abort(new DOMException("The operation timed out.", "TimeoutError"));
-    }, this.#timeoutMs);
+    }, effectiveTimeoutMs);
     const init = {
       method,
       headers: mergedHeaders,
@@ -5194,33 +5249,31 @@ ${effectiveConstraints}`;
     });
   }
   /**
-   * Trigger IDP login for end user via browser.
+   * Mint an end-user IDP sign-in session (link-based, headless).
    *
-   * Opens the app's configured IDP login page in the user's default browser.
-   * Polls for completion and returns the user's IDP JWT token.
+   * The split, pure counterpart to {@link authenticate}. Returns an
+   * {@link AuthSession} carrying the IDP `authUrl` to hand to the end user
+   * and a `sessionToken` to poll with {@link pollAuthSession}. Unlike
+   * `authenticate`, this method:
    *
-   * After `authenticate()` completes, the returned `userToken` is installed
-   * as the active `userTokenGetter` on this instance and automatically used
-   * for subsequent `request()` calls that use identity resolution.
+   * - does **not** open a browser (hand `authUrl` to a remote user over any
+   *   channel — a Slack DM, an MCP client, a printed link), and
+   * - does **not** install a `userTokenGetter` on the instance, so it is
+   *   safe on a shared SDK instance that resolves a JWT per request.
    *
-   * .. warning::
+   * `sessionToken` is a persistable handle: a headless consumer can seal it,
+   * poll in a background loop, and resume a pending session after a restart.
    *
-   *     **`authenticate()` overwrites any constructor-supplied `userTokenGetter`.**
-   *     If you pass `userTokenGetter` to the `_VaultClient` constructor and then
-   *     call `authenticate()`, the constructor getter is silently replaced for
-   *     the lifetime of the instance — a fresh `_VaultClient` instance is the
-   *     only way to restore the original getter. This is intentional for
-   *     interactive CLI flows but can surprise web backends that mix both
-   *     patterns. Prefer one or the other per `_VaultClient` instance.
+   * Scope: requires an app key with the `idp_users:write` scope. Sign-in is
+   * app-initiated (agents do not start user logins).
    *
-   * @param options - Optional configuration (timeout in milliseconds, default 300000 = 5 min)
-   * @returns AuthResult with userToken and userInfo
-   * @throws ConnectTimeoutError if authentication times out
-   * @throws AlterSDKError if session creation or authentication fails
+   * @returns AuthSession with `authUrl`, `sessionToken`, `expiresIn`, `expiresAt`.
+   * @throws AlterSDKError if the SDK is closed or the backend rejects the request.
+   * @throws NetworkError if the backend is unreachable.
+   * @throws TimeoutError if the request to the backend times out.
    */
-  async authenticate(options) {
+  async createAuthSession() {
     this.#assertNotClosed();
-    const timeoutMs = options?.timeout ?? 3e5;
     const actorHeaders = this.#getActorRequestHeaders();
     const sessionPath = "/sdk/auth/session";
     const sessionBodyStr = JSON.stringify({});
@@ -5250,64 +5303,199 @@ ${effectiveConstraints}`;
     }
     this.#cacheActorIdFromResponse(sessionResp);
     await this.#handleErrorResponse(sessionResp);
-    const sessionData = await sessionResp.json();
-    await __VaultClient.#openBrowserOrPrint(
-      sessionData.auth_url,
-      "Open this URL to authenticate"
+    let data;
+    try {
+      data = await sessionResp.json();
+    } catch {
+      throw new BackendError("Auth session response body is not valid JSON");
+    }
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+      throw new BackendError("Auth session response body is not a JSON object");
+    }
+    return new AuthSession(
+      data
     );
-    const startTime = Date.now();
+  }
+  /**
+   * Poll an end-user sign-in session to completion.
+   *
+   * The polling half of the link-based sign-in flow. Use this when your code
+   * minted the session itself via {@link createAuthSession} and you need to
+   * block until the user finishes IDP login. {@link authenticate} is the
+   * all-in-one CLI convenience (mint + open browser + poll + install token);
+   * this method is the polling half on its own and — like
+   * {@link createAuthSession} — installs **no** `userTokenGetter`. The caller
+   * decides what to do with the returned token.
+   *
+   * Transient network blips and non-200 responses are retried until the
+   * deadline (a remote user may take minutes to complete login); only a
+   * terminal IDP error, an expired session, or the timeout end the loop.
+   *
+   * Scope: requires an app key with the `idp_users:read` scope.
+   *
+   * @param sessionToken - A session token from {@link createAuthSession}.
+   * @param options - `timeoutMs` (default 300000) and `pollIntervalMs`
+   *   (default 2000). The Python SDK's equivalent takes seconds by ecosystem
+   *   convention; the two SDKs intentionally differ in unit.
+   * @returns AuthResult with the user's IDP JWT (`userToken`) and `userInfo`.
+   * @throws AlterValueError if `sessionToken` is empty.
+   * @throws AlterSDKError if the SDK is closed or the IDP returned a terminal
+   *   error / the session expired.
+   * @throws ConnectTimeoutError if the user did not complete login in time.
+   */
+  async pollAuthSession(sessionToken, options) {
+    this.#assertNotClosed();
+    if (typeof sessionToken !== "string" || sessionToken.trim().length === 0) {
+      throw new AlterValueError("sessionToken must be a non-empty string");
+    }
+    const timeoutMs = options?.timeoutMs ?? 3e5;
+    const pollIntervalMs = options?.pollIntervalMs ?? 2e3;
+    const deadline = Date.now() + timeoutMs;
     while (true) {
-      if (Date.now() - startTime > timeoutMs) {
-        throw new ConnectTimeoutError(
-          "Authentication timed out",
-          { timeout: timeoutMs }
-        );
-      }
-      await new Promise((resolve2) => setTimeout(resolve2, 2e3));
-      const pollPath = "/sdk/auth/poll";
-      const pollBodyStr = JSON.stringify({ session_token: sessionData.session_token });
-      const pollHmac = this.#computeHmacHeaders("POST", pollPath, pollBodyStr);
-      let pollResp;
-      try {
-        pollResp = await this.#alterClient.post(pollPath, {
-          body: pollBodyStr,
-          headers: { ...actorHeaders, ...pollHmac, "Content-Type": "application/json" }
-        });
-      } catch {
-        continue;
-      }
-      this.#cacheActorIdFromResponse(pollResp);
-      if (!pollResp.ok) {
-        continue;
-      }
-      const pollData = await pollResp.json();
-      if (pollData.status === "completed") {
-        const userToken = pollData.user_token;
-        if (!userToken) {
+      this.#assertNotClosed();
+      const remainingBudget = deadline - Date.now();
+      const waitMs = Math.max(
+        0,
+        Math.min(Math.max(remainingBudget, 0), AUTH_POLL_SERVER_WAIT_MS)
+      );
+      const pollData = await this.#pollAuthSessionOnce(sessionToken, waitMs);
+      if (pollData) {
+        if (pollData.status === "completed") {
+          const userToken = pollData.user_token;
+          if (!userToken) {
+            throw new AlterSDKError(
+              "Authentication completed but no user token was returned by the IDP"
+            );
+          }
+          return new AuthResult({
+            user_token: userToken,
+            user_info: pollData.user_info
+          });
+        }
+        if (pollData.status === "error") {
           throw new AlterSDKError(
-            "Authentication completed but no user token was returned by the IDP"
+            `Authentication failed: ${pollData.error_message || "unknown error"}`
           );
         }
-        if (this.#userTokenGetter !== null) {
-          this.#logger.warn(
-            "[alter-sdk] authenticate() replaced a previously-set userTokenGetter on this _VaultClient instance. Subsequent requests will use the authenticate() token, not the constructor getter."
+        if (pollData.status === "expired") {
+          throw new AlterSDKError("Authentication session expired");
+        }
+        if (pollData.status !== "pending") {
+          throw new AlterSDKError(
+            `Unexpected auth poll status from server: ${String(pollData.status)}`
           );
         }
-        this.#userTokenGetter = () => userToken;
-        return new AuthResult({
-          user_token: userToken,
-          user_info: pollData.user_info
-        });
       }
-      if (pollData.status === "error") {
-        throw new AlterSDKError(
-          pollData.error_message ?? "Authentication failed"
-        );
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await new Promise(
+        (resolve2) => setTimeout(resolve2, Math.min(pollIntervalMs, remaining))
+      );
+    }
+    throw new ConnectTimeoutError("Authentication timed out", { timeoutMs });
+  }
+  /**
+   * Single sign-in poll attempt (INTERNAL).
+   *
+   * Returns the parsed poll body, or `null` to signal a transient failure
+   * (network blip or non-200) that the caller should retry. Matches the
+   * Python SDK's resilient poll: a long sign-in poll survives brief server
+   * hiccups rather than aborting the whole flow.
+   */
+  async #pollAuthSessionOnce(sessionToken, waitMs = 0) {
+    const actorHeaders = this.#getActorRequestHeaders();
+    const pollPath = "/sdk/auth/poll";
+    const pollBody = { session_token: sessionToken };
+    if (waitMs > 0) pollBody.wait_ms = waitMs;
+    const pollBodyStr = JSON.stringify(pollBody);
+    const pollHmac = this.#computeHmacHeaders("POST", pollPath, pollBodyStr);
+    const requestTimeoutMs = waitMs > 0 ? waitMs + AUTH_POLL_HTTP_BUFFER_MS : void 0;
+    let pollResp;
+    try {
+      pollResp = await this.#alterClient.post(pollPath, {
+        body: pollBodyStr,
+        headers: { ...actorHeaders, ...pollHmac, "Content-Type": "application/json" },
+        timeoutMs: requestTimeoutMs
+      });
+    } catch (e) {
+      if (e instanceof TypeError || e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError")) {
+        return null;
       }
-      if (pollData.status === "expired") {
-        throw new AlterSDKError("Authentication session expired");
+      throw e;
+    }
+    this.#cacheActorIdFromResponse(pollResp);
+    if (!pollResp.ok) {
+      if (PERMANENT_POLL_STATUSES.has(pollResp.status)) {
+        await this.#handleErrorResponse(pollResp);
       }
+      return null;
+    }
+    let parsed;
+    try {
+      parsed = await pollResp.json();
+    } catch {
+      throw new BackendError("Auth session poll response body is not valid JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new BackendError("Auth session poll response body is not a JSON object");
+    }
+    const data = parsed;
+    if (typeof data.status !== "string" || data.status.length === 0) {
+      throw new BackendError(
+        "Auth session poll response missing required 'status' field",
+        { field: "status" }
+      );
+    }
+    return data;
+  }
+  /**
+   * Trigger IDP login for end user via browser (bundled CLI convenience).
+   *
+   * Opens the app's configured IDP login page in the user's default browser.
+   * Polls for completion and returns the user's IDP JWT token.
+   *
+   * After `authenticate()` completes, the returned `userToken` is installed
+   * as the active `userTokenGetter` on this instance and automatically used
+   * for subsequent `request()` calls that use identity resolution.
+   *
+   * This composes the two split primitives: {@link createAuthSession} (mint) +
+   * {@link pollAuthSession} (poll). For headless / remote / multi-tenant
+   * sign-in, call the primitives directly — they open no browser and install
+   * no `userTokenGetter`.
+   *
+   * .. warning::
+   *
+   *     **`authenticate()` overwrites any constructor-supplied `userTokenGetter`.**
+   *     If you pass `userTokenGetter` to the `_VaultClient` constructor and then
+   *     call `authenticate()`, the constructor getter is silently replaced for
+   *     the lifetime of the instance — a fresh `_VaultClient` instance is the
+   *     only way to restore the original getter. This is intentional for
+   *     interactive CLI flows but can surprise web backends that mix both
+   *     patterns. Prefer one or the other per `_VaultClient` instance. The
+   *     split primitives never install a getter, so prefer them when this
+   *     side effect is unwanted.
+   *
+   * @param options - Optional configuration (timeout in milliseconds, default 300000 = 5 min)
+   * @returns AuthResult with userToken and userInfo
+   * @throws ConnectTimeoutError if authentication times out
+   * @throws AlterSDKError if session creation or authentication fails
+   */
+  async authenticate(options) {
+    this.#assertNotClosed();
+    const timeoutMs = options?.timeout ?? 3e5;
+    const session = await this.createAuthSession();
+    await __VaultClient.#openBrowserOrPrint(
+      session.authUrl,
+      "Open this URL to authenticate"
+    );
+    const result = await this.pollAuthSession(session.sessionToken, { timeoutMs });
+    if (this.#userTokenGetter !== null) {
+      this.#logger.warn(
+        "[alter-sdk] authenticate() replaced a previously-set userTokenGetter on this _VaultClient instance. Subsequent requests will use the authenticate() token, not the constructor getter."
+      );
     }
+    this.#userTokenGetter = () => result.userToken;
+    return result;
   }
   /**
    * Poll the Connect session for completion status (INTERNAL).
@@ -6439,6 +6627,20 @@ var App = class _App {
     return this.#client.createConnectSessionForError(...args);
   }
   // ── Auth (operator-only) ───────────────────────────────────────────────
+  /**
+   * Mint a link-based end-user sign-in session (no browser, no instance
+   * mutation). See {@link _VaultClient.createAuthSession}.
+   */
+  async createAuthSession() {
+    return this.#client.createAuthSession();
+  }
+  /**
+   * Poll a sign-in session to completion, returning the user's JWT.
+   * See {@link _VaultClient.pollAuthSession}.
+   */
+  async pollAuthSession(...args) {
+    return this.#client.pollAuthSession(...args);
+  }
   async authenticate(options) {
     return this.#client.authenticate(options);
   }
@@ -6871,7 +7073,7 @@ var DEFAULT_BASE_URL = "https://backend.alterauth.com";
 var PAT_API_PREFIX = "/api/v1/dev-portal";
 var HTTP_ERROR_THRESHOLD = 400;
 var DEFAULT_TIMEOUT_MS = 3e4;
-var CLI_VERSION = "0.3.2";
+var CLI_VERSION = "0.3.3";
 var USER_AGENT = buildUserAgent();
 function buildUserAgent() {
   let osTag = "";
@@ -7017,6 +7219,9 @@ var DashboardClient = class {
   policy;
   /** Audit log read surface (CLI `alter audit` subcommands). */
   audit;
+  /** OAuth + managed-secret grant inspect/revoke (CLI `alter grants`
+   * subcommands). Requires ``dashboard_grants:read`` / ``:admin``. */
+  grants;
   #closed = false;
   constructor(options = {}) {
     const resolvedPat = options.pat ?? (typeof process !== "undefined" ? process.env.ALTER_PAT : void 0);
@@ -7066,6 +7271,7 @@ var DashboardClient = class {
     this.managedSecrets = new ManagedSecretsNamespace(this);
     this.policy = new PolicyNamespace(this);
     this.audit = new AuditNamespace(this);
+    this.grants = new GrantsNamespace(this);
   }
   /**
    * Release internal state. The default `fetch` is a global; this is
@@ -8029,9 +8235,8 @@ var AuditNamespace = class {
   }
   /** List runtime audit-log rows. Requires `dashboard_audit:read`.
    *
-   * NOTE: returns ``{logs, total, limit, offset, is_truncated}`` — a
-   * non-standard envelope (the audit routes pre-date the canonical
-   * ``items`` shape). Consumers narrow ``logs`` themselves.
+   * Returns the canonical envelope ``{items, total, limit, offset, has_more}``
+   * plus the distinct ``is_truncated`` cap-signal (the 10k offset cap was hit).
    */
   async list(options = {}) {
     const query = optionsToQuery({
@@ -8044,8 +8249,8 @@ var AuditNamespace = class {
   }
   /** List dashboard / CLI admin actions. Requires `dashboard_audit:read`.
    *
-   * NOTE: returns ``{events, total, limit, offset}``; consumers narrow
-   * ``events`` themselves.
+   * Returns the canonical envelope ``{items, total, limit, offset, has_more}``
+   * plus the distinct ``is_truncated`` cap-signal.
    */
   async listPortalActions(options = {}) {
     const query = optionsToQuery({
@@ -8063,8 +8268,8 @@ var AuditNamespace = class {
   }
   /** List grant-lifecycle events. Requires `dashboard_audit:read`.
    *
-   * NOTE: returns ``{events, total, limit, offset}``; consumers narrow
-   * ``events`` themselves.
+   * Returns the canonical envelope ``{items, total, limit, offset, has_more}``
+   * plus the distinct ``is_truncated`` cap-signal.
    */
   async listGrantEvents(options = {}) {
     const query = optionsToQuery({
@@ -8082,8 +8287,8 @@ var AuditNamespace = class {
   }
   /** List trace summaries. Requires `dashboard_audit:read`.
    *
-   * NOTE: returns ``{traces, total, limit, offset}``; consumers narrow
-   * ``traces`` themselves.
+   * Returns the canonical envelope ``{items, total, limit, offset, has_more}``
+   * plus the distinct ``is_event_window_capped`` signal.
    */
   async listTraces(options = {}) {
     const query = optionsToQuery({
@@ -8110,6 +8315,59 @@ var AuditNamespace = class {
     return expectDict(body, "audit.get_trace", 200);
   }
 };
+var GrantsNamespace = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /**
+   * List grants on an app. Returns the polymorphic OAuth +
+   * managed-secret list (each row carries a ``grant_type``
+   * discriminator). Requires ``dashboard_grants:read``.
+   *
+   * Wire envelope: ``{ grants, total, limit, offset, has_more,
+   * is_truncated }`` — non-canonical (pre-dates the ``items``
+   * convention). Consumers narrow ``grants`` themselves.
+   */
+  async list(appId, options = {}) {
+    const app = encodePathParam(appId, "appId");
+    const query = optionsToQuery({
+      // The backend's FastAPI Query param on this GET route is named
+      // ``grant_status`` (no alias). The public-facing CLI flag is
+      // ``--status`` for ergonomics; we map it to the wire name here.
+      grant_status: options.status,
+      provider_id: options.provider_id,
+      app_user_id: options.app_user_id,
+      search: options.search,
+      limit: options.limit ?? 100,
+      offset: options.offset ?? 0
+    });
+    const body = await this.#client._call(
+      "GET",
+      `/apps/${app}/grants`,
+      "grants.list",
+      { query }
+    );
+    return expectDict(body, "grants.list", 200);
+  }
+  /**
+   * Revoke a grant on an app. Cascade-revokes any active agent
+   * delegations under the grant and best-effort deletes the vault
+   * token. Recoverable via re-consent through the OAuth flow.
+   * Requires ``dashboard_grants:admin``.
+   */
+  async revoke(appId, grantId, options = {}) {
+    const app = encodePathParam(appId, "appId");
+    const grant = encodePathParam(grantId, "grantId");
+    const body = await this.#client._call(
+      "POST",
+      `/apps/${app}/grants/${grant}/revoke`,
+      "grants.revoke",
+      { jsonBody: { reason: options.reason ?? null } }
+    );
+    return expectDict(body, "grants.revoke", 200);
+  }
+};
 
 // src/portal-factory.ts
 async function createPortalClient() {
@@ -9299,10 +9557,6 @@ function parseRelativeFromNow(raw, direction) {
 }
 
 // src/commands/audit.ts
-function normalizeAuditEnvelope(result, domainKey) {
-  const { [domainKey]: items, ...rest } = result;
-  return { ...rest, items };
-}
 function resolveStartDate(start, since) {
   if (start !== void 0 && since !== void 0) {
     process.stderr.write(
@@ -9415,7 +9669,7 @@ function buildAuditCommand() {
           offset: options.offset
         });
         const logs = validateRows(
-          extractArrayField(result, "logs", "audit.list"),
+          extractArrayField(result, "items", "audit.list"),
           {
             id: isString,
             timestamp: isString,
@@ -9434,7 +9688,7 @@ function buildAuditCommand() {
         if (format === "table" || format === "jsonl") {
           emit(format, logs, AUDIT_COLUMNS);
         } else {
-          emit(format, normalizeAuditEnvelope(result, "logs"));
+          emit(format, result);
         }
       });
     }
@@ -9481,7 +9735,7 @@ function buildAuditCommand() {
           offset: options.offset
         });
         const events = validateRows(
-          extractArrayField(result, "events", "audit.list_portal_actions"),
+          extractArrayField(result, "items", "audit.list_portal_actions"),
           {
             id: isString,
             timestamp: isString,
@@ -9496,7 +9750,7 @@ function buildAuditCommand() {
         if (format === "table" || format === "jsonl") {
           emit(format, events, PORTAL_ACTION_COLUMNS);
         } else {
-          emit(format, normalizeAuditEnvelope(result, "events"));
+          emit(format, result);
         }
       });
     }
@@ -9532,7 +9786,7 @@ function buildAuditCommand() {
           offset: options.offset
         });
         const events = validateRows(
-          extractArrayField(result, "events", "audit.list_grant_events"),
+          extractArrayField(result, "items", "audit.list_grant_events"),
           {
             id: isString,
             timestamp: isString,
@@ -9546,7 +9800,7 @@ function buildAuditCommand() {
         if (format === "table" || format === "jsonl") {
           emit(format, events, GRANT_EVENT_COLUMNS);
         } else {
-          emit(format, normalizeAuditEnvelope(result, "events"));
+          emit(format, result);
         }
       });
     }
@@ -9573,7 +9827,7 @@ function buildAuditCommand() {
           offset: options.offset
         });
         const traces = validateRows(
-          extractArrayField(result, "traces", "audit.list_traces"),
+          extractArrayField(result, "items", "audit.list_traces"),
           {
             trace_id: isString,
             first_timestamp: isString,
@@ -9588,7 +9842,7 @@ function buildAuditCommand() {
         if (format === "table" || format === "jsonl") {
           emit(format, traces, TRACE_COLUMNS);
         } else {
-          emit(format, normalizeAuditEnvelope(result, "traces"));
+          emit(format, result);
         }
       });
     }
@@ -9630,7 +9884,13 @@ var DEFAULT_SCOPES = [
   // ``:delete`` and ``:admin`` are deliberate opt-ins via ``--scopes``
   // per the destructive-action policy in CLAUDE.md.
   "dashboard_secrets:read",
-  "dashboard_secrets:write"
+  "dashboard_secrets:write",
+  // ``dashboard_grants`` (added to backend catalog v4). Read is in
+  // defaults so ``alter grants list`` works out of the box; ``:admin``
+  // (revoke) requires explicit ``--scopes`` opt-in per the
+  // destructive-action policy in CLAUDE.md — same posture as
+  // ``dashboard_keys:admin``.
+  "dashboard_grants:read"
 ];
 function deriveDashboardUrl(baseUrl) {
   return baseUrl.replace(/^https:\/\/backend\./, "https://portal.");
@@ -9920,7 +10180,17 @@ var DASHBOARD_RESOURCE_VERBS = {
   // grant + delegation + audit anchor and vault-deletes the stored
   // credential (irrecoverable). Backend catalog v3, see
   // ``apps/backend/app/core/scopes/catalog.py`` _DASHBOARD_RESOURCES_V3.
-  dashboard_secrets: ["read", "write", "delete"]
+  dashboard_secrets: ["read", "write", "delete"],
+  // ``dashboard_grants`` (catalog v4): inspect + revoke end-user
+  // grants on an app. ``:read`` → GET /apps/{id}/grants (list, OAuth
+  // + managed-secret polymorphic); ``:admin`` → POST /apps/{id}/grants/
+  // {id}/revoke. Grant revocation is RECOVERABLE per CLAUDE.md's
+  // destructive-action tiers (re-consent restores access), so the
+  // revoke route stays on the standard ``:admin`` verb — no separate
+  // ``:delete`` tier. ``:write`` omitted because grants are minted by
+  // the OAuth flow, never via direct API edits. Backend source of
+  // truth: ``_DASHBOARD_RESOURCES_V4``.
+  dashboard_grants: ["read", "admin"]
 };
 function parseScopesFlag(raw) {
   if (typeof raw !== "string") {
@@ -10568,8 +10838,148 @@ function buildCompletionCommand() {
   return completion;
 }
 
-// src/commands/keys.ts
+// src/commands/grants.ts
 import { Command as Command6 } from "commander";
+var GRANT_COLUMNS = [
+  { label: "ID", get: (g) => g.id, maxWidth: 36 },
+  { label: "TYPE", get: (g) => g.grant_type },
+  { label: "PROVIDER", get: (g) => g.provider_name, maxWidth: 24 },
+  { label: "STATUS", get: (g) => g.status },
+  {
+    label: "USER",
+    get: (g) => g.user_identifier ?? g.account_display_name ?? "\u2014",
+    maxWidth: 32
+  },
+  { label: "CREATED", get: (g) => g.created_at }
+];
+function buildGrantsCommand() {
+  const grants = new Command6("grants").description(
+    "Inspect and revoke end-user grants (OAuth + managed-secret)"
+  );
+  grants.command("list").description(
+    "List grants on an app (OAuth + managed-secret, polymorphic). Requires dashboard_grants:read scope."
+  ).option(
+    "--app <app-id>",
+    "App ID. Falls back to ALTER_APP_ID env or .alter/config.yaml"
+  ).option(
+    "--status <status>",
+    "Filter by status: active | expired | revoked. Case-sensitive \u2014 matches the backend's ``GrantStatus`` enum verbatim."
+  ).option(
+    "--provider <id>",
+    "Filter by provider ID (e.g. 'google', 'github', or a managed-secret template slug)."
+  ).option(
+    "--app-user <uuid>",
+    "Filter by end-user (app_user_id, internal UUID)",
+    parseUuidArgument("--app-user")
+  ).option(
+    "--search <text>",
+    "Substring search on user_identifier OR account_display_name (max 100 chars; backend-side filter)"
+  ).option(
+    "--limit <n>",
+    "Page size (1\u20131000)",
+    parseBoundedInt("--limit", 1, 1e3),
+    100
+  ).option(
+    "--offset <n>",
+    "Pagination offset (oversize values clamp to 10,000 with is_truncated=true)",
+    parseNonNegativeInt("--offset"),
+    0
+  ).option(
+    "--output <format>",
+    "Output format: json|jsonl|table (default: table)",
+    "table"
+  ).action(
+    async (options) => {
+      const format = coerceOutputFormat(options.output);
+      const status = validateChoice(
+        "--status",
+        options.status,
+        ["active", "expired", "revoked"]
+      );
+      if (options.search !== void 0) {
+        validateNoControlCharsOrExit("--search", options.search);
+      }
+      await withClient(async (client) => {
+        const result = await client.grants.list(resolveAppIdOrExit(options.app), {
+          status,
+          provider_id: options.provider,
+          app_user_id: options.appUser,
+          search: options.search,
+          limit: options.limit,
+          offset: options.offset
+        });
+        const rows = validateRows(
+          extractArrayField(result, "grants", "grants.list"),
+          {
+            id: isString,
+            grant_type: isString,
+            provider_id: isString,
+            provider_name: isString,
+            status: isString,
+            user_identifier: isOptionalString,
+            account_display_name: isOptionalString,
+            created_at: isString,
+            last_used_at: isOptionalString,
+            expires_at: isOptionalString
+          },
+          "grants.list"
+        );
+        if (format === "table" || format === "jsonl") {
+          emit(format, rows, GRANT_COLUMNS);
+        } else {
+          emit(format, result);
+        }
+      });
+    }
+  );
+  grants.command("revoke").description(
+    "Revoke a grant immediately (cascades to active agent delegations under the grant + best-effort vault token delete). Recoverable via re-consent through the OAuth flow. Requires dashboard_grants:admin scope."
+  ).option(
+    "--app <app-id>",
+    "App ID. Falls back to ALTER_APP_ID env or .alter/config.yaml"
+  ).requiredOption(
+    "--grant <grant-id>",
+    "Grant ID",
+    parseUuidArgument("--grant")
+  ).option(
+    "--reason <text>",
+    "Optional operator-supplied reason recorded on the audit row."
+  ).option("--yes", "Skip the interactive y/N prompt").action(
+    async (options) => {
+      if (options.reason !== void 0) {
+        validateNoControlCharsOrExit("--reason", options.reason);
+      }
+      await withClient(async (client) => {
+        if (!options.yes) {
+          const ok = await promptYesNo(
+            `Revoke grant ${options.grant}? This cascades to any active agent delegations. [y/N]: `
+          );
+          if (!ok) {
+            process.stderr.write("alter: revoke cancelled.\n");
+            process.exit(EXIT_CANCELLED);
+          }
+        }
+        const result = await client.grants.revoke(
+          resolveAppIdOrExit(options.app),
+          options.grant,
+          { reason: options.reason }
+        );
+        const revokedAt = result.revoked_at;
+        if (typeof revokedAt === "string") {
+          process.stdout.write(`Revoked grant ${options.grant} at ${revokedAt}.
+`);
+        } else {
+          process.stdout.write(`Revoked grant ${options.grant}.
+`);
+        }
+      });
+    }
+  );
+  return grants;
+}
+
+// src/commands/keys.ts
+import { Command as Command7 } from "commander";
 var KEY_TYPE_MAP = {
   runtime: "rk",
   agent: "ak"
@@ -10583,7 +10993,7 @@ var KEY_COLUMNS2 = [
   { label: "STATUS", get: (k) => k.revoked_at ? "revoked" : "active" }
 ];
 function buildKeysCommand() {
-  const keys = new Command6("keys").description("Manage scoped API keys");
+  const keys = new Command7("keys").description("Manage scoped API keys");
   keys.command("list").description("List keys for an app").option("--app <app-id>", "App ID. Falls back to ALTER_APP_ID env or .alter/config.yaml").option(
     "--output <format>",
     "Output format: json|jsonl|table (default: table)",
@@ -10805,9 +11215,9 @@ function buildKeysCommand() {
 // src/commands/link.ts
 import { existsSync as existsSync4 } from "fs";
 import { join as join5 } from "path";
-import { Command as Command7 } from "commander";
+import { Command as Command8 } from "commander";
 function buildLinkCommand() {
-  const link = new Command7("link").description(
+  const link = new Command8("link").description(
     "Pin the current directory tree to a default app_id so subsequent commands (``keys``, ``agents``, ``providers``, ``policy``) don't need --app."
   ).argument("[app-id]", "App ID to pin. Omitted when --status is passed.").option(
     "--force",
@@ -10835,7 +11245,7 @@ function buildLinkCommand() {
   return link;
 }
 function buildUnlinkCommand() {
-  return new Command7("unlink").description("Remove the current directory's .alter/config.yaml pin.").action(async () => {
+  return new Command8("unlink").description("Remove the current directory's .alter/config.yaml pin.").action(async () => {
     const removed = removeWorkspaceConfig();
     if (removed) {
       process.stdout.write(
@@ -10923,7 +11333,7 @@ async function runStatus() {
 
 // src/commands/managed-secrets.ts
 import { readFileSync as readFileSync6 } from "fs";
-import { Command as Command8, Option } from "commander";
+import { Command as Command9, Option } from "commander";
 var PRINCIPAL_TYPES = ["user", "group", "system", "agent"];
 var CREDENTIAL_TYPES = [
   "bearer_token",
@@ -11277,7 +11687,7 @@ var SECRET_COLUMNS = [
   { label: "GRANTS", get: (s) => String(s.grant_count) },
   { label: "CREATED", get: (s) => s.created_at }
 ];
-var GRANT_COLUMNS = [
+var GRANT_COLUMNS2 = [
   { label: "GRANT_ID", get: (g) => g.grant_id, maxWidth: 36 },
   { label: "PRINCIPAL", get: (g) => g.principal_type },
   { label: "LABEL", get: (g) => g.label ?? "\u2014", maxWidth: 24 },
@@ -11309,7 +11719,7 @@ var ACCESS_COLUMNS = [
   { label: "AGENT", get: (a) => a.via_agent_name ?? "\u2014" }
 ];
 function buildGrantsSubcommand() {
-  const grants = new Command8("grants").description(
+  const grants = new Command9("grants").description(
     "Manage grants on managed secrets (list / create / update / revoke)."
   );
   grants.command("list <secret-id>").description("List grants for a managed secret").option("--app <app-id>", "App ID. Falls back to ALTER_APP_ID env or .alter/config.yaml").option(
@@ -11347,7 +11757,7 @@ function buildGrantsSubcommand() {
           created_at: isString,
           expires_at: isOptionalString
         }, "managed-secrets.grants.list");
-        emit(format, rows, GRANT_COLUMNS);
+        emit(format, rows, GRANT_COLUMNS2);
       });
     }
   );
@@ -11377,7 +11787,7 @@ function buildGrantsSubcommand() {
           created_at: isString,
           expires_at: isOptionalString
         }, "managed-secrets.grants.list-for-agent");
-        emit(format, rows, GRANT_COLUMNS);
+        emit(format, rows, GRANT_COLUMNS2);
       });
     }
   );
@@ -11581,7 +11991,7 @@ function buildGrantsSubcommand() {
   return grants;
 }
 function buildGroupsSubcommand() {
-  const groups = new Command8("groups").description(
+  const groups = new Command9("groups").description(
     "App-user-group autocomplete + group detail helpers."
   );
   groups.command("list").description("List app-user-groups (Group-tab picker source)").option("--app <app-id>", "App ID").option("--idp <uuid>", "Filter by identity provider id").option("--search <substring>", "Substring search on group name / external_group_id").option("--limit <n>", "Page size (default: 50)", parseBoundedInt("--limit", 1, 200)).option("--offset <n>", "Starting offset (default: 0)", parseNonNegativeInt("--offset")).option(
@@ -11653,7 +12063,7 @@ function buildGroupsSubcommand() {
   return groups;
 }
 function buildManagedSecretsCommand() {
-  const root = new Command8("managed-secrets").description(
+  const root = new Command9("managed-secrets").description(
     "Manage managed-secret credentials, grants, and access (CRUD + autocomplete helpers)."
   );
   root.command("templates").description("List the managed-secret template catalog for an app").option("--app <app-id>", "App ID").option("--limit <n>", "Page size (default: 200)", parseBoundedInt("--limit", 1, 1e3)).option("--offset <n>", "Starting offset (default: 0)", parseNonNegativeInt("--offset")).option(
@@ -11724,7 +12134,7 @@ function buildManagedSecretsCommand() {
   root.command("create").description("Create a managed secret + base grant").option("--app <app-id>", "App ID").option(
     "--input <path>",
     "JSON wire body from file (@path) or stdin (-). Mirrors `gh api --input`. Replaces per-field flags; the body is sent to POST /apps/{id}/managed-secrets verbatim. Use when you have the body pre-computed (CI / templating) or want one stable shape across the CLI."
-  ).option("--slug <slug>", "Stable kebab-case identifier (e.g. 'openai-api'). Required unless --input is supplied.").option("--name <name>", "Human display name. Required unless --input is supplied.").option("--description <text>", "Free-form description").option("--template <id>", "Template id (e.g. 'openai'); omit for custom").addOption(
+  ).option("--name <name>", "Human display name. Required unless --input is supplied.").option("--description <text>", "Free-form description").option("--template <id>", "Template id (e.g. 'openai'); omit for custom").addOption(
     // ``--credential-type`` is enum-validated at RUNTIME (see the
     // per-field branch below) rather than parse-time so a typo'd
     // value alongside ``--input @body.json`` (which discards the
@@ -11769,7 +12179,6 @@ function buildManagedSecretsCommand() {
           "--input"
         );
         const perField = [
-          "slug",
           "name",
           "description",
           "template",
@@ -11802,12 +12211,6 @@ function buildManagedSecretsCommand() {
         });
         return;
       }
-      if (options.slug === void 0) {
-        process.stderr.write(
-          "alter: managed-secrets create requires --slug (or use --input @file.json to supply the full body)\n"
-        );
-        process.exit(EXIT_USAGE);
-      }
       if (options.name === void 0) {
         process.stderr.write(
           "alter: managed-secrets create requires --name (or use --input @file.json to supply the full body)\n"
@@ -11820,7 +12223,6 @@ function buildManagedSecretsCommand() {
         CREDENTIAL_TYPES
       );
       validateNoControlCharsOrExit("--name", options.name);
-      validateNoControlCharsOrExit("--slug", options.slug);
       if (options.description !== void 0) {
         validateNoControlCharsOrExit("--description", options.description);
       }
@@ -11844,7 +12246,6 @@ function buildManagedSecretsCommand() {
       const additionalCredentials = loadedCredentials !== void 0 ? loadedCredentials.additionalCredentials : options.credentialField;
       const additionalInjections = options.injectionRule !== void 0 ? loadInjectionRules(options.injectionRule) : void 0;
       const body = {
-        slug: options.slug,
         name: options.name,
         credential_type: options.credentialType,
         credential_value: credentialValue
@@ -12103,7 +12504,7 @@ function buildManagedSecretsCommand() {
 }
 
 // src/commands/pats.ts
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 async function whoami(options) {
   const client = await createPortalClient();
   let exitCode = 0;
@@ -12125,7 +12526,7 @@ async function whoami(options) {
   }
 }
 function buildPatsCommand() {
-  const pats = new Command9("pats").description("Inspect Personal Access Tokens");
+  const pats = new Command10("pats").description("Inspect Personal Access Tokens");
   pats.command("whoami").description("Show the currently-active PAT and its scopes").option("--output <format>", "Output format: json|table (default: json)", "json").action(async (options) => {
     const format = coerceOutputFormat(options.output);
     await whoami({ output: format });
@@ -12134,9 +12535,9 @@ function buildPatsCommand() {
 }
 
 // src/commands/policy.ts
-import { Command as Command10 } from "commander";
+import { Command as Command11 } from "commander";
 function buildPolicyCommand() {
-  const policy = new Command10("policy").description(
+  const policy = new Command11("policy").description(
     "Read app-level policy (read-only \u2014 edits via dashboard)"
   );
   policy.command("show-app").description(
@@ -12153,7 +12554,7 @@ function buildPolicyCommand() {
 
 // src/commands/providers.ts
 import { readFileSync as readFileSync7 } from "fs";
-import { Command as Command11 } from "commander";
+import { Command as Command12 } from "commander";
 var CREDENTIAL_SOURCES = ["custom", "shared_dev"];
 var PROVIDER_STATUSES = ["active", "disabled"];
 var PROVIDER_COLUMNS = [
@@ -12232,7 +12633,7 @@ function surfaceProviderResponse(row) {
   }
 }
 function buildProvidersCommand() {
-  const providers = new Command11("providers").description(
+  const providers = new Command12("providers").description(
     "Manage OAuth provider configs"
   );
   providers.command("list").description("List OAuth provider configs for an app").option("--app <app-id>", "App ID. Falls back to ALTER_APP_ID env or .alter/config.yaml").option(
@@ -12469,9 +12870,9 @@ function buildProvidersCommand() {
 }
 
 // src/commands/sdk-passthrough.ts
-import { Command as Command12 } from "commander";
+import { Command as Command13 } from "commander";
 function buildSdkPassthroughCommand() {
-  const cmd = new Command12("sdk-passthrough").description(
+  const cmd = new Command13("sdk-passthrough").description(
     "Escape hatch for ad-hoc runtime SDK calls (vault.request). Uses a runtime API key, NOT a PAT."
   );
   cmd.command("request <grant-id>").description(
@@ -12600,7 +13001,7 @@ function buildSdkPassthroughCommand() {
 // src/commands/self-update.ts
 import { spawnSync } from "child_process";
 import { platform as platform4 } from "os";
-import { Command as Command13 } from "commander";
+import { Command as Command14 } from "commander";
 var CLI_PACKAGE = "@alter-ai/cli";
 function runNpmInstall(spec) {
   const result = spawnSync(
@@ -12655,7 +13056,7 @@ function probeNpmInstall() {
   };
 }
 function buildSelfUpdateCommand() {
-  return new Command13("self-update").description("Upgrade the alter CLI globally via npm").option("--to <version>", "Pin to a specific version instead of @latest").option(
+  return new Command14("self-update").description("Upgrade the alter CLI globally via npm").option("--to <version>", "Pin to a specific version instead of @latest").option(
     "--dry-run",
     "Print the npm install command that would run, without executing it"
   ).action(async (options) => {
@@ -12710,7 +13111,7 @@ function buildSelfUpdateCommand() {
 
 // src/program.ts
 function buildProgram() {
-  const program2 = new Command14();
+  const program2 = new Command15();
   program2.name("alter").description("Alter Vault command-line interface").version(package_default.version);
   program2.option(
     "--fields <list>",
@@ -12739,6 +13140,7 @@ function buildProgram() {
   program2.addCommand(buildManagedSecretsCommand());
   program2.addCommand(buildPolicyCommand());
   program2.addCommand(buildAuditCommand());
+  program2.addCommand(buildGrantsCommand());
   program2.addCommand(buildPatsCommand());
   program2.addCommand(buildLinkCommand());
   program2.addCommand(buildUnlinkCommand());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alter-ai/cli",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Command-line interface for the Alter Vault dev portal — scripted dashboard automation.",
   "type": "module",
   "bin": {
@@ -43,7 +43,7 @@
     "tsup": "^8.0.0",
     "tsx": "^4.7.0",
     "typescript": "^5.5.0",
-    "vitest": "^3.0.0"
+    "vitest": "^4.1.8"
   },
   "engines": {
     "node": ">=20.10.0"