@corvio/admin-cli 0.1.0-beta.2 → 0.1.0-beta.20

package/README.md

@@ -1,12 +1,14 @@
 # Corvio Platform Administrator CLI
 
-Official read-only CLI for bounded Corvio platform investigations. It is separate from the Workspace CLI and accepts only a short-lived `cva_` credential.
+Official read-only CLI for bounded Corvio platform investigations. It is separate from the Workspace CLI and accepts only a short-lived `cva_` credential, supplied by environment or administrator device link.
 
 ```bash
-npm install --global @corvio/admin-cli
-export CORVIO_ADMIN_API_KEY='cva_...'
-corvio-admin auth status
+npm install --global @corvio/admin-cli@beta
+corvio-admin auth login
+corvio-admin auth status --json
 corvio-admin catalog --json
 ```
 
-Every data query requires a purpose and returns an auditable receipt. This package contains no ordinary Workspace commands. See [the administrator CLI guide](https://corvio.ai/developers/admin-cli).
+For Agents and CI, inject `CORVIO_ADMIN_API_KEY='cva_...'`; it takes precedence over the stored device-link credential. Every data query requires a purpose and returns an auditable receipt. This package contains no ordinary Workspace commands. See [the administrator CLI guide](https://corvio.ai/developers/admin-cli).
+
+Unknown/duplicate options, malformed bounds, and invalid JSON fail locally. API calls use the same bounded transport/runtime safety policy as the Workspace CLI. `corvio-admin skill download` reads the protected manifest first and verifies the archive SHA-256 before writing the zip.

package/dist/cli.js

@@ -1,28 +1,59 @@
 #!/usr/bin/env node
 
+import { createHash } from "node:crypto";
+
 import {
   ApiClient,
   CliError,
   EXIT,
+  assertKnownOptions,
+  assertPositionalCount,
+  clearAdminCredential,
   listOption,
   normalizeApiBase,
   numberOption,
+  openBrowser,
   option,
   readAdminCredential,
   readTextFile,
+  resolveNpmUpdateStatus,
   runMain,
+  sleep,
+  storeAdminCredential,
+  writeBinaryFile,
   writeResult,
 } from "./core.js";
 
-const VERSION = "0.1.0-beta.2";
+const VERSION = "0.1.0-beta.20";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const USER_AGENT = `corvio-admin-cli/${VERSION}`;
+const GLOBAL_OPTIONS = Object.freeze(["api-base", "json", "no-input", "help", "version"]);
+const COMMAND_OPTIONS = Object.freeze({
+  "auth:login": ["force", "scopes"],
+  "auth:status": [],
+  "auth:logout": [],
+  "capabilities:": [],
+  "update:check": [],
+  "skill:download": ["output"],
+  "catalog:": [],
+  "query:": ["file", "purpose", "dataset", "fields", "group-by", "metrics", "filters", "order-by", "limit", "cursor"],
+  "data:query": ["file", "purpose", "dataset", "fields", "group-by", "metrics", "filters", "order-by", "limit", "cursor"],
+  "workspaces:list": ["purpose", "workspace-id", "status", "limit", "cursor"],
+  "users:list": ["purpose", "workspace-id", "status", "limit", "cursor"],
+  "worker-jobs:list": ["purpose", "workspace-id", "status", "limit", "cursor"],
+  "runs:list": ["purpose", "workspace-id", "status", "limit", "cursor"],
+  "runs:content": ["id", "purpose"],
+  "usage:events": ["purpose", "workspace-id", "status", "limit", "cursor"],
+  "usage:summary": ["purpose", "workspace-id", "status", "limit", "cursor"],
+  "receipts:get": ["id"],
+});
 
 const HELP = `Corvio Platform Administrator CLI ${VERSION}
 
 Usage:
-  corvio-admin auth status
+  corvio-admin auth login|status|logout
   corvio-admin capabilities
+  corvio-admin skill download [--output <path>]
   corvio-admin catalog
   corvio-admin query|data query --file <request.json>
   corvio-admin workspaces list --purpose <reason>
@@ -31,26 +62,78 @@ Usage:
   corvio-admin worker-jobs list --purpose <reason>
   corvio-admin usage events|summary --purpose <reason>
   corvio-admin receipts get <id>
+  corvio-admin update check
 
 Authentication:
-  Set CORVIO_ADMIN_API_KEY to a short-lived cva_ key.
+  CORVIO_ADMIN_API_KEY=cva_... takes precedence over the stored device-link login.
+  Run 'corvio-admin auth login' when no environment key is configured.
 
 This package contains no Workspace ask, search, docs, files, sync, or share commands.
 `;
 
-function baseUrl(options) {
-  return normalizeApiBase(options["api-base"] || process.env.CORVIO_API_BASE, DEFAULT_API_BASE);
+function resourcePath(value) {
+  return encodeURIComponent(String(value));
+}
+
+function validateInvocation(options, positionals) {
+  const [command, rawAction] = positionals;
+  if (!command || command === "help" || command === "version" || options.help || options.version) return;
+  const defaultActions = {
+    update: "check",
+    workspaces: "list",
+    users: "list",
+    "worker-jobs": "list",
+  };
+  const action = ["capabilities", "catalog", "query"].includes(command)
+    ? ""
+    : rawAction || defaultActions[command] || "";
+  const schema = COMMAND_OPTIONS[`${command}:${action}`];
+  if (!schema) {
+    throw new CliError(`Unknown administrator command: ${positionals.join(" ")}`, {
+      code: "unknown_command",
+    });
+  }
+  assertKnownOptions(options, [...GLOBAL_OPTIONS, ...schema]);
+  const maximum = new Set(["runs:content", "receipts:get"]).has(`${command}:${action}`)
+    ? 3
+    : action
+      ? 2
+      : 1;
+  assertPositionalCount(positionals, maximum);
+}
+
+function parseJsonValue(value, optionName) {
+  try {
+    return JSON.parse(String(value));
+  } catch {
+    throw new CliError(`Option --${optionName} must contain valid JSON.`, {
+      code: "invalid_json_option",
+    });
+  }
+}
+
+function baseUrl(options, credential = null) {
+  return normalizeApiBase(
+    options["api-base"]
+      || process.env.CORVIO_ADMIN_API_BASE
+      || process.env.CORVIO_API_BASE
+      || credential?.metadata?.api_base,
+    DEFAULT_API_BASE,
+  );
 }
 
-function client(options) {
-  const credential = readAdminCredential();
+async function client(options) {
+  const credential = await readAdminCredential();
   if (!credential) {
-    throw new CliError("Set CORVIO_ADMIN_API_KEY to a short-lived cva_ key.", {
+    throw new CliError("Set CORVIO_ADMIN_API_KEY or run `corvio-admin auth login`.", {
       code: "admin_auth_required",
       exitCode: EXIT.AUTH,
     });
   }
-  return new ApiClient({ baseUrl: baseUrl(options), credential: credential.key, userAgent: USER_AGENT });
+  return {
+    api: new ApiClient({ baseUrl: baseUrl(options, credential), credential: credential.key, userAgent: USER_AGENT }),
+    credential,
+  };
 }
 
 function listQuery(options) {
@@ -58,13 +141,90 @@ function listQuery(options) {
     purpose: option(options, "purpose", { required: true }),
     workspace_id: options["workspace-id"],
     status: options.status,
-    limit: numberOption(options, "limit", 100),
+    limit: numberOption(options, "limit", 100, { maximum: 200 }),
     cursor: options.cursor,
   };
 }
 
+async function authLogin(options) {
+  const current = await readAdminCredential();
+  if (current && !options.force) {
+    const api = new ApiClient({ baseUrl: baseUrl(options, current), credential: current.key, userAgent: USER_AGENT });
+    const identity = await api.request("/me");
+    writeResult({ authenticated: true, source: current.source, identity }, { json: options.json });
+    return;
+  }
+  const requestedScopes = listOption(options, "scopes", [
+    "admin_data:read",
+    "admin_support:read",
+    "admin_costs:read",
+  ]);
+  if (requestedScopes.includes("admin_content:read") && !options.force) {
+    throw new CliError(
+      "Requesting admin_content:read requires --force and should be limited to a specific Run investigation.",
+      { code: "admin_content_scope_confirmation_required" },
+    );
+  }
+  const api = new ApiClient({ baseUrl: baseUrl(options), userAgent: USER_AGENT });
+  const authorization = await api.request("/admin/auth/device-authorizations", {
+    method: "POST",
+    auth: false,
+    body: {
+      client_name: "Corvio Platform Administrator CLI",
+      cli_version: VERSION,
+      scopes: requestedScopes,
+    },
+  });
+  process.stderr.write(`Open ${authorization.verification_uri_complete}\nCode: ${authorization.user_code}\n`);
+  if (!options["no-input"]) await openBrowser(authorization.verification_uri_complete);
+
+  const expiresAt = Date.now() + Number(authorization.expires_in || 600) * 1000;
+  let intervalSeconds = Math.max(5, Number(authorization.interval || 5));
+  let token;
+  while (Date.now() < expiresAt) {
+    await sleep(intervalSeconds * 1000);
+    try {
+      token = await api.request("/admin/auth/device-token", {
+        method: "POST",
+        auth: false,
+        body: { device_code: authorization.device_code },
+      });
+      break;
+    } catch (error) {
+      if (!(error instanceof CliError)) throw error;
+      if (error.code === "authorization_pending") continue;
+      if (error.code === "slow_down") {
+        intervalSeconds = Math.min(30, intervalSeconds + 5);
+        continue;
+      }
+      throw error;
+    }
+  }
+  if (!token?.secret || token.audience !== "platform_admin") {
+    throw new CliError("Administrator device authorization expired; run `corvio-admin auth login` again.", {
+      code: "expired_token",
+      exitCode: EXIT.AUTH,
+    });
+  }
+  await storeAdminCredential({ ...token, api_base: baseUrl(options) });
+  const authenticatedApi = new ApiClient({ baseUrl: baseUrl(options), credential: token.secret, userAgent: USER_AGENT });
+  const identity = await authenticatedApi.request("/me");
+  writeResult({
+    authenticated: true,
+    source: "device_link",
+    audience: identity.api_key?.audience,
+    scopes: identity.api_key?.scopes || [],
+    expires_at: token.expires_at,
+  }, { json: options.json });
+}
+
 async function authStatus(options) {
-  const api = client(options);
+  const credential = await readAdminCredential();
+  if (!credential) {
+    writeResult({ authenticated: false, sources: ["CORVIO_ADMIN_API_KEY", "device_link"] }, { json: options.json });
+    return;
+  }
+  const api = new ApiClient({ baseUrl: baseUrl(options, credential), credential: credential.key, userAgent: USER_AGENT });
   const identity = await api.request("/me");
   if (identity.api_key?.audience !== "platform_admin") {
     throw new CliError("The configured key is not a platform administrator credential.", {
@@ -72,23 +232,64 @@ async function authStatus(options) {
       exitCode: EXIT.AUTH,
     });
   }
-  writeResult({ authenticated: true, source: "environment", identity }, { json: options.json });
+  writeResult({ authenticated: true, source: credential.source, identity }, { json: options.json });
+}
+
+async function authLogout(options) {
+  const credential = await readAdminCredential();
+  if (!credential) {
+    writeResult({ authenticated: false, changed: false }, { json: options.json });
+    return;
+  }
+  if (credential.source === "environment") {
+    throw new CliError("CORVIO_ADMIN_API_KEY is managed by the parent environment and cannot be removed by the CLI.", {
+      code: "environment_credential_managed_externally",
+      exitCode: EXIT.AUTH,
+    });
+  }
+  const api = new ApiClient({ baseUrl: baseUrl(options, credential), credential: credential.key, userAgent: USER_AGENT });
+  await api.request("/admin/auth/credentials/current:revoke", { method: "POST" });
+  await clearAdminCredential();
+  writeResult({ authenticated: false, revoked: true }, { json: options.json });
 }
 
 async function capabilities(options) {
-  const api = client(options);
+  const { api, credential } = await client(options);
   const [index, identity] = await Promise.all([api.request("/admin"), api.request("/me")]);
-  writeResult({ cli_version: VERSION, api: index, principal: identity }, { json: options.json });
+  writeResult({ cli_version: VERSION, auth_source: credential.source, api: index, principal: identity }, { json: options.json });
+}
+
+async function updateCheck(options) {
+  const { api } = await client(options);
+  const index = await api.request("/admin");
+  const result = await resolveNpmUpdateStatus({
+    currentVersion: VERSION,
+    policy: index?.distribution?.admin_cli || {
+      package: "@corvio/admin-cli",
+      dist_tag: "beta",
+    },
+    userAgent: USER_AGENT,
+  });
+  writeResult(result, { json: options.json });
 }
 
 async function catalog(options) {
-  writeResult(await client(options).request("/admin/data/catalog"), { json: options.json });
+  const { api } = await client(options);
+  writeResult(await api.request("/admin/data/catalog"), { json: options.json });
 }
 
 async function query(options) {
   let body;
   if (options.file) {
-    body = JSON.parse(await readTextFile(options.file));
+    try {
+      body = JSON.parse(await readTextFile(options.file));
+    } catch (error) {
+      if (error?.code === "ENOENT") throw error;
+      throw new CliError("--file must contain a valid JSON request object.", { code: "invalid_json_file" });
+    }
+    if (!body || Array.isArray(body) || typeof body !== "object") {
+      throw new CliError("--file must contain a JSON object.", { code: "invalid_json_file" });
+    }
     if (options.purpose) body.purpose = options.purpose;
   } else {
     body = {
@@ -96,26 +297,56 @@ async function query(options) {
       purpose: option(options, "purpose", { required: true }),
       fields: listOption(options, "fields"),
       group_by: listOption(options, "group-by"),
-      metrics: options.metrics ? JSON.parse(options.metrics) : [],
-      filters: options.filters ? JSON.parse(options.filters) : [],
-      order_by: options["order-by"] ? JSON.parse(options["order-by"]) : [],
-      limit: numberOption(options, "limit", 100),
+      metrics: options.metrics ? parseJsonValue(options.metrics, "metrics") : [],
+      filters: options.filters ? parseJsonValue(options.filters, "filters") : [],
+      order_by: options["order-by"] ? parseJsonValue(options["order-by"], "order-by") : [],
+      limit: numberOption(options, "limit", 100, { maximum: 200 }),
       cursor: options.cursor || null,
     };
   }
-  writeResult(await client(options).request("/admin/data/query", { method: "POST", body }), { json: options.json });
+  const { api } = await client(options);
+  writeResult(await api.request("/admin/data/query", { method: "POST", body }), { json: options.json });
 }
 
 async function listResource(options, resource) {
-  writeResult(await client(options).request(`/admin/${resource}`, { query: listQuery(options) }), { json: options.json });
+  const { api } = await client(options);
+  writeResult(await api.request(`/admin/${resource}`, { query: listQuery(options) }), { json: options.json });
+}
+
+async function downloadSkill(options) {
+  const { api } = await client(options);
+  const output = String(options.output || "corvio-admin-data.zip");
+  const manifest = await api.request("/admin/skill/manifest.json");
+  const bytes = await api.requestBytes("/admin/skill/corvio-admin-data.zip");
+  const actualHash = createHash("sha256").update(bytes).digest("hex");
+  if (!manifest.archive_sha256 || actualHash !== manifest.archive_sha256) {
+    throw new CliError("Administrator Skill archive did not match its manifest SHA-256.", {
+      code: "admin_skill_integrity_mismatch",
+      exitCode: EXIT.REMOTE,
+    });
+  }
+  const path = await writeBinaryFile(output, bytes);
+  writeResult({
+    downloaded: true,
+    output: path,
+    install: `npx skills add ${path}`,
+  }, { json: options.json });
 }
 
 async function main({ options, positionals }) {
   const [command, action, id] = positionals;
   if (options.version || command === "version") return writeResult(VERSION, { json: options.json });
   if (options.help || !command || command === "help") return writeResult(HELP.trimEnd(), { json: false });
-  if (command === "auth" && action === "status") return authStatus(options);
+  validateInvocation(options, positionals);
+  if (command === "auth") {
+    if (action === "login") return authLogin(options);
+    if (action === "status") return authStatus(options);
+    if (action === "logout") return authLogout(options);
+    throw new CliError("auth action must be login, status, or logout.");
+  }
   if (command === "capabilities") return capabilities(options);
+  if (command === "update" && (action || "check") === "check") return updateCheck(options);
+  if (command === "skill" && action === "download") return downloadSkill(options);
   if (command === "catalog") return catalog(options);
   if (command === "query") return query(options);
   if (command === "data" && action === "query") return query(options);
@@ -126,15 +357,18 @@ async function main({ options, positionals }) {
   if (command === "runs" && action === "content") {
     const runId = id || option(options, "id", { required: true });
     const purpose = option(options, "purpose", { required: true });
-    return writeResult(await client(options).request(`/admin/runs/${runId}/content`, { query: { purpose } }), { json: options.json });
+    const { api } = await client(options);
+    return writeResult(await api.request(`/admin/runs/${resourcePath(runId)}/content`, { query: { purpose } }), { json: options.json });
   }
   if (command === "usage" && action === "events") return listResource(options, "usage/events");
   if (command === "usage" && action === "summary") {
-    return writeResult(await client(options).request("/admin/usage/summary", { query: listQuery(options) }), { json: options.json });
+    const { api } = await client(options);
+    return writeResult(await api.request("/admin/usage/summary", { query: listQuery(options) }), { json: options.json });
   }
   if (command === "receipts" && action === "get") {
     const receiptId = id || option(options, "id", { required: true });
-    return writeResult(await client(options).request(`/admin/data/query-receipts/${receiptId}`), { json: options.json });
+    const { api } = await client(options);
+    return writeResult(await api.request(`/admin/data/query-receipts/${resourcePath(receiptId)}`), { json: options.json });
   }
   throw new CliError(`Unknown administrator command: ${positionals.join(" ")}`);
 }