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

package/README.md

@@ -1,12 +1,12 @@
 # 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).

package/dist/cli.js

@@ -4,25 +4,31 @@ import {
   ApiClient,
   CliError,
   EXIT,
+  clearAdminCredential,
   listOption,
   normalizeApiBase,
   numberOption,
+  openBrowser,
   option,
   readAdminCredential,
   readTextFile,
   runMain,
+  sleep,
+  storeAdminCredential,
+  writeBinaryFile,
   writeResult,
 } from "./core.js";
 
-const VERSION = "0.1.0-beta.2";
+const VERSION = "0.1.0-beta.3";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const USER_AGENT = `corvio-admin-cli/${VERSION}`;
 
 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>
@@ -33,24 +39,34 @@ Usage:
   corvio-admin receipts get <id>
 
 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 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) {
@@ -63,8 +79,85 @@ function listQuery(options) {
   };
 }
 
+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,17 +165,36 @@ 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 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) {
@@ -103,19 +215,39 @@ async function query(options) {
       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 bytes = await api.requestBytes("/admin/skill/corvio-admin-data.zip");
+  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);
+  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 === "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 +258,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/${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/${receiptId}`), { json: options.json });
   }
   throw new CliError(`Unknown administrator command: ${positionals.join(" ")}`);
 }

package/dist/core.js

@@ -163,6 +163,51 @@ export class ApiClient {
     }
     return payload;
   }
+
+  async requestBytes(path, { query, headers = {}, auth = true } = {}) {
+    const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`);
+    for (const [key, value] of Object.entries(query || {})) {
+      if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, String(value));
+    }
+    const requestHeaders = {
+      accept: "application/zip, application/octet-stream",
+      "user-agent": this.userAgent,
+      ...headers,
+    };
+    if (auth) {
+      if (!this.credential) {
+        throw new CliError("Corvio authentication is required.", { code: "auth_required", exitCode: EXIT.AUTH });
+      }
+      requestHeaders.authorization = `Bearer ${this.credential}`;
+    }
+    let response;
+    try {
+      response = await this.fetchImpl(url, { method: "GET", headers: requestHeaders });
+    } catch (cause) {
+      throw new CliError(`Unable to reach Corvio: ${cause instanceof Error ? cause.message : String(cause)}`, {
+        code: "network_error",
+        exitCode: EXIT.REMOTE,
+      });
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (!response.ok) {
+      const text = new TextDecoder().decode(bytes);
+      let payload = {};
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        payload = { message: text.slice(0, 500) };
+      }
+      const envelope = payload?.error || payload?.detail || payload || {};
+      throw new CliError(String(envelope.message || envelope.code || `Corvio request failed (${response.status}).`), {
+        code: String(envelope.code || `http_${response.status}`),
+        status: response.status,
+        exitCode: exitCodeForStatus(response.status),
+        details: envelope.details || null,
+      });
+    }
+    return bytes;
+  }
 }
 
 function configRoot(env = process.env) {
@@ -175,6 +220,10 @@ export function workspaceCredentialPath(env = process.env) {
   return join(configRoot(env), "credentials.json");
 }
 
+export function adminCredentialPath(env = process.env) {
+  return join(configRoot(env), "admin-credentials.json");
+}
+
 export async function readWorkspaceCredential(env = process.env) {
   const environmentKey = String(env.CORVIO_API_KEY || "").trim();
   if (environmentKey) {
@@ -241,16 +290,66 @@ export async function clearWorkspaceCredential(env = process.env) {
   return path;
 }
 
-export function readAdminCredential(env = process.env) {
+export async function readAdminCredential(env = process.env) {
   const key = String(env.CORVIO_ADMIN_API_KEY || "").trim();
-  if (!key) return null;
-  if (!key.startsWith("cva_")) {
-    throw new CliError("CORVIO_ADMIN_API_KEY must be a platform administrator cva_ key.", {
-      code: "invalid_admin_key",
+  if (key) {
+    if (!key.startsWith("cva_")) {
+      throw new CliError("CORVIO_ADMIN_API_KEY must be a platform administrator cva_ key.", {
+        code: "invalid_admin_key",
+        exitCode: EXIT.AUTH,
+      });
+    }
+    return { key, source: "environment", metadata: null };
+  }
+  const path = adminCredentialPath(env);
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+  } catch (cause) {
+    if (cause?.code === "ENOENT") return null;
+    throw new CliError("Stored Corvio administrator credentials are unreadable.", {
+      code: "admin_credential_store_invalid",
+      exitCode: EXIT.AUTH,
+    });
+  }
+  const storedKey = String(parsed.api_key || "").trim();
+  if (!storedKey.startsWith("cva_")) {
+    throw new CliError("Stored Corvio administrator credentials are invalid; run `corvio-admin auth login` again.", {
+      code: "admin_credential_store_invalid",
       exitCode: EXIT.AUTH,
     });
   }
-  return { key, source: "environment" };
+  return { key: storedKey, source: "device_link", metadata: parsed };
+}
+
+export async function storeAdminCredential(payload, env = process.env) {
+  const path = adminCredentialPath(env);
+  const root = dirname(path);
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  await chmod(root, 0o700).catch(() => {});
+  const document = {
+    version: 1,
+    api_key: payload.secret,
+    key_id: payload.key_id,
+    audience: payload.audience,
+    api_base: payload.api_base,
+    scopes: payload.scopes || [],
+    expires_at: payload.expires_at,
+    created_at: payload.created_at || new Date().toISOString(),
+    source: "device_link",
+  };
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  await chmod(temporary, 0o600);
+  await rename(temporary, path);
+  await chmod(path, 0o600);
+  return { path };
+}
+
+export async function clearAdminCredential(env = process.env) {
+  const path = adminCredentialPath(env);
+  await rm(path, { force: true });
+  return path;
 }
 
 export function writeResult(value, { json = false, stdout = process.stdout } = {}) {
@@ -313,6 +412,13 @@ export async function writeTextFile(path, content) {
   return target;
 }
 
+export async function writeBinaryFile(path, content) {
+  const target = resolve(String(path));
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, content);
+  return target;
+}
+
 export function requireConfirmation(options, action) {
   if (!options.yes) {
     throw new CliError(`${action} requires --yes.`, { code: "confirmation_required" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@corvio/admin-cli",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.3",
   "description": "Official read-only Corvio platform administrator CLI.",
   "type": "module",
   "bin": {