app/cli/lib/identity.ts

// Resolves "who is this remote command acting as, and what credential
// does it send" -- one place, used by `zz work`/`zz review`/
// `zz repo submit`, in priority order:
//
//  1. ZZ_ID="<username>:<token>" -- for automated/headless contexts
//     with no interactive `zz login` session at all (a CI runner, a
//     container with no ~/.zz). A real, standing credential someone
//     else is managing the lifecycle of -- never minted or revoked
//     here.
//  2. ZZ_ID_FILE=<path to a file with that same "<username>:<token>"
//     text> -- the same thing, out of an env var (visible in `ps`,
//     shell history, some CI log capture) and into a file instead.
//  3. --as <name>: your own `zz login` session resolves who YOU are;
//     <name> expands to "<your username>[<name>]" (the standard
//     managed-agent naming -- see worker/src/accountsDb.ts's
//     computeUsername) unless it already looks fully-qualified
//     (contains "@" or "["). A FRESH token is minted for it right
//     now, using your own session's existing mint authority
//     (requireTokenMintAuthority on the server: you, or an agent you
//     created) -- and the caller is expected to revoke it when the
//     session ends (releaseIdentity below), so nothing long-lived
//     sits on disk. This is NOT server-side impersonation -- your own
//     token never acts as another agent; this mints and uses that
//     agent's own real token, scoped to one run.
//  4. No --as: your own `zz login` session, directly (long-lived,
//     untouched -- never minted or revoked here).
import { readFileSync } from "node:fs";
import { apiBase, requireCredentials } from "./credentials.js";
import { apiFetch } from "./api.js";
import { resolveUserPath } from "./paths.js";

export interface ResolvedIdentity {
  apiBase: string;
  token: string;
  username: string;
  /** True only for a token minted by resolveIdentity itself (the --as path) -- the one case the caller should revoke on exit (see releaseIdentity). Your own login (ZZ_ID included) is a standing credential someone else manages; never revoked here. */
  ephemeral: boolean;
}

function parseIdPair(raw: string, source: string): { username: string; token: string } {
  const idx = raw.indexOf(":");
  if (idx === -1) throw new Error(`${source} must be "<username>:<token>", got "${raw}"`);
  return { username: raw.slice(0, idx).trim(), token: raw.slice(idx + 1).trim() };
}

export async function resolveIdentity(asName?: string): Promise<ResolvedIdentity> {
  if (process.env.ZZ_ID) {
    const { username, token } = parseIdPair(process.env.ZZ_ID, "ZZ_ID");
    return { apiBase: apiBase(), token, username, ephemeral: false };
  }
  if (process.env.ZZ_ID_FILE) {
    const raw = readFileSync(resolveUserPath(process.env.ZZ_ID_FILE), "utf8").trim();
    const { username, token } = parseIdPair(raw, "ZZ_ID_FILE");
    return { apiBase: apiBase(), token, username, ephemeral: false };
  }

  const human = requireCredentials();
  if (!asName) return { apiBase: human.apiBase, token: human.token, username: human.username, ephemeral: false };

  const fullUsername = /[@[]/.test(asName) ? asName : `${human.username}[${asName}]`;
  const { token } = await apiFetch<{ token: string }>("POST", `/api/agents/${encodeURIComponent(fullUsername)}/tokens`, undefined, human.token);
  return { apiBase: human.apiBase, token, username: fullUsername, ephemeral: true };
}

/** Best-effort cleanup for an ephemeral (--as) identity -- revokes the token it minted, using that same token (the server's self-revoke endpoint needs no id, just the bearer presenting it). A no-op for anything resolveIdentity didn't itself mint. Swallows errors: called from exit paths (Ctrl+C, SIGTERM, a thrown error), where a failed revoke shouldn't block the process from actually exiting -- a short-lived leaked token is a minor, bounded exposure, not worth hanging the CLI over. */
export async function releaseIdentity(identity: ResolvedIdentity | null): Promise<void> {
  if (!identity?.ephemeral) return;
  try {
    await apiFetch("POST", "/api/me/revoke", undefined, identity.token);
  } catch {
    // best-effort
  }
}