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

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,32 @@ import {
   ApiClient,
   CliError,
   EXIT,
+  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.4";
 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>
@@ -31,26 +38,37 @@ 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 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 +81,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 +167,50 @@ 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) {
@@ -103,19 +231,40 @@ 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 === "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 +275,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

@@ -105,10 +105,92 @@ export function normalizeApiBase(value, fallback) {
   return raw.endsWith("/v1") ? raw : `${raw}/v1`;
 }
 
+function parseSemver(value) {
+  const match = String(value || "").trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
+  if (!match) return null;
+  return {
+    core: match.slice(1, 4).map((item) => Number.parseInt(item, 10)),
+    pre: match[4] ? match[4].split(".") : [],
+  };
+}
+
+export function compareVersions(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) return 0;
+  for (let index = 0; index < 3; index += 1) {
+    if (a.core[index] !== b.core[index]) return a.core[index] > b.core[index] ? 1 : -1;
+  }
+  if (a.pre.length === 0 && b.pre.length > 0) return 1;
+  if (b.pre.length === 0 && a.pre.length > 0) return -1;
+  for (let index = 0; index < Math.max(a.pre.length, b.pre.length); index += 1) {
+    if (a.pre[index] === undefined) return -1;
+    if (b.pre[index] === undefined) return 1;
+    if (a.pre[index] === b.pre[index]) continue;
+    const aNumber = /^\d+$/.test(a.pre[index]) ? Number.parseInt(a.pre[index], 10) : null;
+    const bNumber = /^\d+$/.test(b.pre[index]) ? Number.parseInt(b.pre[index], 10) : null;
+    if (aNumber !== null && bNumber !== null) return aNumber > bNumber ? 1 : -1;
+    if (aNumber !== null) return -1;
+    if (bNumber !== null) return 1;
+    return a.pre[index] > b.pre[index] ? 1 : -1;
+  }
+  return 0;
+}
+
+export async function resolveNpmUpdateStatus({
+  currentVersion,
+  policy,
+  userAgent,
+  allowRegistryFailure = false,
+  fetchImpl = globalThis.fetch,
+  registryBase = process.env.CORVIO_NPM_REGISTRY_BASE || "https://registry.npmjs.org",
+}) {
+  const packageName = String(policy?.package || "").trim();
+  const distTag = String(policy?.dist_tag || "beta").trim();
+  if (!packageName) throw new CliError("The API did not advertise an npm package.", { code: "update_policy_invalid" });
+  const encoded = encodeURIComponent(packageName).replace("%40", "@");
+  let latestVersion = null;
+  let registryError = null;
+  try {
+    const registry = String(registryBase).replace(/\/+$/, "");
+    const response = await fetchImpl(`${registry}/${encoded}`, {
+      headers: { accept: "application/json", "user-agent": userAgent },
+      signal: AbortSignal.timeout(2500),
+    });
+    if (!response.ok) throw new Error(`npm registry returned ${response.status}`);
+    const metadata = await response.json();
+    latestVersion = String(metadata?.["dist-tags"]?.[distTag] || "").trim() || null;
+  } catch (error) {
+    registryError = error instanceof Error ? error.message : String(error);
+    if (!allowRegistryFailure) {
+      throw new CliError(`Unable to check npm for updates: ${registryError}`, {
+        code: "update_check_failed",
+        exitCode: EXIT.REMOTE,
+      });
+    }
+  }
+  const minimum = String(policy.minimum_supported_version || "").trim() || null;
+  return {
+    package: packageName,
+    channel: String(policy.channel || distTag),
+    dist_tag: distTag,
+    current_version: currentVersion,
+    latest_published_version: latestVersion,
+    reviewed_version: String(policy.reviewed_version || "").trim() || null,
+    minimum_supported_version: minimum,
+    update_available: Boolean(latestVersion && compareVersions(latestVersion, currentVersion) > 0),
+    supported: minimum ? compareVersions(currentVersion, minimum) >= 0 : true,
+    install_command: String(policy.install_command || `npm install --global ${packageName}@${distTag}`),
+    automatic_install: false,
+    ...(registryError ? { registry_error: registryError } : {}),
+  };
+}
+
 export class ApiClient {
-  constructor({ baseUrl, credential = null, userAgent, fetchImpl = globalThis.fetch }) {
+  constructor({ baseUrl, credential = null, workspaceId = null, userAgent, fetchImpl = globalThis.fetch }) {
     this.baseUrl = baseUrl.replace(/\/+$/, "");
     this.credential = credential;
+    this.workspaceId = String(workspaceId || "").trim() || null;
     this.userAgent = userAgent;
     this.fetchImpl = fetchImpl;
   }
@@ -129,6 +211,10 @@ export class ApiClient {
         throw new CliError("Corvio authentication is required.", { code: "auth_required", exitCode: EXIT.AUTH });
       }
       requestHeaders.authorization = `Bearer ${this.credential}`;
+      if (this.workspaceId) {
+        requestHeaders["X-Corvio-Workspace-Id"] = this.workspaceId;
+        requestHeaders["X-Corvio-Workspace-Context-Contract"] = "required-v1";
+      }
     }
     let response;
     try {
@@ -163,6 +249,80 @@ 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}`;
+      if (this.workspaceId) {
+        requestHeaders["X-Corvio-Workspace-Id"] = this.workspaceId;
+        requestHeaders["X-Corvio-Workspace-Context-Contract"] = "required-v1";
+      }
+    }
+    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;
+  }
+
+  async putUrl(url, content, { headers = {} } = {}) {
+    let response;
+    try {
+      response = await this.fetchImpl(String(url), {
+        method: "PUT",
+        headers,
+        body: content,
+      });
+    } catch (cause) {
+      throw new CliError(`Unable to upload the file: ${cause instanceof Error ? cause.message : String(cause)}`, {
+        code: "upload_network_error",
+        exitCode: EXIT.REMOTE,
+      });
+    }
+    if (!response.ok) {
+      const message = (await response.text()).slice(0, 500);
+      throw new CliError(message || `File upload failed (${response.status}).`, {
+        code: "upload_failed",
+        status: response.status,
+        exitCode: EXIT.REMOTE,
+      });
+    }
+    return { ok: true, status: response.status };
+  }
 }
 
 function configRoot(env = process.env) {
@@ -175,11 +335,19 @@ export function workspaceCredentialPath(env = process.env) {
   return join(configRoot(env), "credentials.json");
 }
 
+export function workspaceContextPath(env = process.env) {
+  return join(configRoot(env), "workspace-context.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) {
-    if (!environmentKey.startsWith("cvk_")) {
-      throw new CliError("CORVIO_API_KEY must be a Workspace cvk_ key.", {
+    if (!environmentKey.startsWith("cvu_") && !environmentKey.startsWith("cvk_")) {
+      throw new CliError("CORVIO_API_KEY must be a user cvu_ key or legacy Workspace cvk_ key.", {
         code: "invalid_workspace_key",
         exitCode: EXIT.AUTH,
       });
@@ -196,14 +364,15 @@ export async function readWorkspaceCredential(env = process.env) {
   }
   const profileName = String(parsed.active_profile || "default");
   const profile = parsed.profiles?.[profileName];
-  const key = String(profile?.api_key || "").trim();
-  if (!key.startsWith("cvk_")) {
+  const metadata = String(parsed.api_key || "").trim() ? parsed : profile;
+  const key = String(metadata?.api_key || "").trim();
+  if (!key.startsWith("cvu_") && !key.startsWith("cvk_")) {
     throw new CliError("Stored Corvio credentials are invalid; run `corvio auth login` again.", {
       code: "credential_store_invalid",
       exitCode: EXIT.AUTH,
     });
   }
-  return { key, source: "device_link", profile: profileName, metadata: profile };
+  return { key, source: "device_link", profile: profileName, metadata };
 }
 
 export async function storeWorkspaceCredential(payload, env = process.env) {
@@ -211,28 +380,73 @@ export async function storeWorkspaceCredential(payload, env = process.env) {
   const root = dirname(path);
   await mkdir(root, { recursive: true, mode: 0o700 });
   await chmod(root, 0o700).catch(() => {});
-  const profileName = String(payload.workspace_id || "default");
+  const document = {
+    version: 2,
+    api_key: payload.secret,
+    key_id: payload.key_id,
+    audience: payload.audience || "user",
+    scopes: payload.scopes || [],
+    expires_at: payload.expires_at || null,
+    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, profile: "default" };
+}
+
+export async function readWorkspaceContext(env = process.env) {
+  const environmentWorkspaceId = String(env.CORVIO_WORKSPACE_ID || "").trim();
+  if (environmentWorkspaceId) {
+    return { workspaceId: environmentWorkspaceId, workspaceName: null, source: "environment" };
+  }
+  const path = workspaceContextPath(env);
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    const workspaceId = String(parsed.active_workspace_id || "").trim();
+    if (!workspaceId) return null;
+    return {
+      workspaceId,
+      workspaceName: String(parsed.active_workspace_name || "").trim() || null,
+      source: "stored",
+    };
+  } catch (cause) {
+    if (cause?.code === "ENOENT") return null;
+    throw new CliError("Stored Corvio Workspace selection is unreadable.", {
+      code: "workspace_context_store_invalid",
+      exitCode: EXIT.AUTH,
+    });
+  }
+}
+
+export async function storeWorkspaceContext({ workspaceId, workspaceName = null }, env = process.env) {
+  const normalizedId = String(workspaceId || "").trim();
+  if (!normalizedId) throw new CliError("Workspace ID is required.", { code: "workspace_selection_required" });
+  const path = workspaceContextPath(env);
+  const root = dirname(path);
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  await chmod(root, 0o700).catch(() => {});
   const document = {
     version: 1,
-    active_profile: profileName,
-    profiles: {
-      [profileName]: {
-        api_key: payload.secret,
-        key_id: payload.key_id,
-        workspace_id: payload.workspace_id,
-        workspace_name: payload.workspace_name,
-        scopes: payload.scopes || [],
-        created_at: payload.created_at || new Date().toISOString(),
-        source: "device_link",
-      },
-    },
+    active_workspace_id: normalizedId,
+    active_workspace_name: String(workspaceName || "").trim() || null,
+    updated_at: new Date().toISOString(),
   };
   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, profile: profileName };
+  return { path, workspaceId: normalizedId };
+}
+
+export async function clearWorkspaceContext(env = process.env) {
+  const path = workspaceContextPath(env);
+  await rm(path, { force: true });
+  return path;
 }
 
 export async function clearWorkspaceCredential(env = process.env) {
@@ -241,16 +455,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,
     });
   }
-  return { key, source: "environment" };
+  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: 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 } = {}) {
@@ -289,13 +553,24 @@ export async function openBrowser(url) {
   const target = String(url);
   const command = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open";
   const args = platform() === "win32" ? ["/c", "start", "", target] : [target];
-  try {
-    const child = spawn(command, args, { detached: true, stdio: "ignore" });
-    child.unref();
-    return true;
-  } catch {
-    return false;
-  }
+  return new Promise((resolvePromise) => {
+    let settled = false;
+    const finish = (opened) => {
+      if (settled) return;
+      settled = true;
+      resolvePromise(opened);
+    };
+    try {
+      const child = spawn(command, args, { detached: true, stdio: "ignore" });
+      child.once("error", () => finish(false));
+      child.once("spawn", () => {
+        child.unref();
+        finish(true);
+      });
+    } catch {
+      finish(false);
+    }
+  });
 }
 
 export async function sleep(milliseconds) {
@@ -313,6 +588,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.4",
   "description": "Official read-only Corvio platform administrator CLI.",
   "type": "module",
   "bin": {