@dharta/cli 0.6.77

package/src/commands/kartas.ts

@@ -0,0 +1,439 @@
+import { randomUUID } from "node:crypto";
+import type { CliContext } from "../context.js";
+import { table } from "../output.js";
+import { maskEnvValue } from "./env.js";
+import { closestChoice, normalizeNonBlank } from "../validators.js";
+
+const DHARTA_AUDIENCES = ["members", "anonymous", "off"] as const;
+const DHARTA_ROLES = ["viewer", "participant", "manager"] as const;
+type KartaAudience = (typeof DHARTA_AUDIENCES)[number];
+type KartaRole = (typeof DHARTA_ROLES)[number];
+
+export interface KartaMember {
+  id: string | number;
+  email: string;
+  role: string;
+  joined_at: string;
+}
+
+export interface KartaRecord {
+  id: string;
+  name: string | null;
+  vanity_slug: string | null;
+  access_audience: string | null;
+  access_model: string;
+  state: string;
+  agent: { id: string | number; slug: string; name: string } | null;
+  url: string | null;
+  members?: KartaMember[];
+}
+
+export interface KartaConfigureOptions {
+  name?: string;
+  slug?: string;
+  access?: string;
+}
+
+export interface KartaListOptions {
+  agent?: string;
+  named?: boolean;
+  archived?: boolean;
+}
+
+export interface KartaNameOptions {
+  name?: string;
+  slug?: string;
+}
+
+export interface KartaCreateOptions {
+  agent?: string;
+  slug?: string;
+  access?: string;
+  members?: string[];
+  memberRole?: string;
+}
+
+export function validateKartaCreateOptions(name: string, options: KartaCreateOptions): void {
+  normalizeNonBlank(name, "dharta name");
+  normalizeNonBlank(options.agent ?? "", "Agent slug");
+  normalizeNonBlank(options.slug ?? "", "dharta vanity slug");
+  normalizeAudience(options.access ?? "members");
+  normalizeRole(options.memberRole ?? "participant");
+  for (const email of options.members ?? []) normalizeNonBlank(email, "karta member email");
+}
+
+export async function kartasCreateData(
+  ctx: CliContext,
+  name: string,
+  options: KartaCreateOptions,
+): Promise<{ karta: KartaRecord }> {
+  validateKartaCreateOptions(name, options);
+  const access = normalizeAudience(options.access ?? "members");
+  const role = normalizeRole(options.memberRole ?? "participant");
+  const agent = normalizeNonBlank(options.agent ?? "", "Agent slug");
+  const slug = normalizeNonBlank(options.slug ?? "", "dharta vanity slug");
+  return ctx.http.request<{ karta: KartaRecord }>({
+    method: "POST",
+    path: "/api/kartas",
+    headers: { "Idempotency-Key": randomUUID() },
+    body: {
+      agent,
+      name: name.trim(),
+      vanity_slug: slug.toLowerCase(),
+      access_audience: access === "off" ? null : access,
+      members: (options.members ?? []).map((email) => ({ email: email.trim(), role })),
+    },
+  });
+}
+
+export async function kartasCreate(ctx: CliContext, name: string, options: KartaCreateOptions): Promise<string> {
+  const { karta } = await kartasCreateData(ctx, name, options);
+  return karta.url
+    ? `Created ${karta.name ?? karta.id}. Stable URL: ${karta.url}`
+    : `Created ${karta.name ?? karta.id}. Stable URL is off.`;
+}
+
+export async function kartasListData(ctx: CliContext, options: KartaListOptions = {}): Promise<KartaRecord[]> {
+  const query = new URLSearchParams();
+  if (options.agent !== undefined) query.set("agent", normalizeNonBlank(options.agent, "Agent slug"));
+  if (options.named) query.set("named", "true");
+  // Archived kartas are hidden by default; --archived lists only those.
+  if (options.archived) query.set("archived", "true");
+  const suffix = query.size > 0 ? `?${query.toString()}` : "";
+  const response = await ctx.http.request<{ data: KartaRecord[] }>({ path: `/api/kartas${suffix}` });
+  return response.data;
+}
+
+export async function kartasList(ctx: CliContext, options: KartaListOptions = {}): Promise<string> {
+  const kartas = await kartasListData(ctx, options);
+  if (kartas.length === 0) return options.named ? "No named kartas yet." : "No kartas yet.";
+  return table(kartas.map((karta) => ({
+    id: karta.id,
+    name: karta.name ?? "—",
+    agent: karta.agent?.slug ?? "—",
+    slug: karta.vanity_slug ?? "—",
+    access: accessLabel(karta),
+    url: karta.url ?? "—",
+  })));
+}
+
+export async function kartasShowData(ctx: CliContext, id: string): Promise<KartaRecord> {
+  const kartaId = normalizeNonBlank(id, "dharta id");
+  const response = await ctx.http.request<{ karta: KartaRecord }>({
+    path: `/api/kartas/${encodeURIComponent(kartaId)}`,
+  });
+  return response.karta;
+}
+
+export async function kartasShow(ctx: CliContext, id: string): Promise<string> {
+  const karta = await kartasShowData(ctx, id);
+  const members = karta.members?.length
+    ? table(karta.members.map((member) => ({
+        id: String(member.id), email: member.email, role: member.role,
+      })))
+    : "No people listed.";
+  return [
+    `karta: ${karta.name ?? karta.id} (${karta.id})`,
+    `Agent: ${karta.agent?.slug ?? "—"}`,
+    `Vanity slug: ${karta.vanity_slug ?? "—"}`,
+    `Stable URL access: ${accessLabel(karta)}`,
+    `Signed-in access: ${karta.access_model === "native_shared" ? "managed here" : "controlled by the existing agent integration"}`,
+    `URL: ${karta.url ?? "—"}`,
+    "",
+    "People",
+    members,
+  ].join("\n");
+}
+
+export function validateKartaConfigureOptions(options: KartaConfigureOptions): void {
+  if (options.name === undefined && options.slug === undefined && options.access === undefined) {
+    throw new Error("Set at least one of --name, --slug, or --access.");
+  }
+  if (options.name !== undefined) normalizeNonBlank(options.name, "dharta name");
+  if (options.slug !== undefined) normalizeNonBlank(options.slug, "dharta vanity slug");
+  if (options.access !== undefined) normalizeAudience(options.access);
+}
+
+export function validateKartaNameOptions(options: KartaNameOptions): void {
+  normalizeNonBlank(options.name ?? "", "dharta name");
+  normalizeNonBlank(options.slug ?? "", "dharta vanity slug");
+}
+
+export async function kartasNameData(
+  ctx: CliContext,
+  id: string,
+  options: KartaNameOptions,
+): Promise<{ karta: KartaRecord }> {
+  validateKartaNameOptions(options);
+  return kartasConfigureData(ctx, id, { name: options.name, slug: options.slug });
+}
+
+export async function kartasName(ctx: CliContext, id: string, options: KartaNameOptions): Promise<string> {
+  const { karta } = await kartasNameData(ctx, id, options);
+  return `Named ${karta.id} as ${karta.name} (/kartas/${karta.vanity_slug}). Stable URL access remains ${accessLabel(karta)}.`;
+}
+
+export async function kartasConfigureData(
+  ctx: CliContext,
+  id: string,
+  options: KartaConfigureOptions,
+): Promise<{ karta: KartaRecord }> {
+  const kartaId = normalizeNonBlank(id, "dharta id");
+  validateKartaConfigureOptions(options);
+  const body: Record<string, unknown> = {};
+  if (options.name !== undefined) body.name = options.name.trim();
+  if (options.slug !== undefined) body.vanity_slug = options.slug.trim().toLowerCase();
+  if (options.access !== undefined) {
+    const access = normalizeAudience(options.access);
+    body.access_audience = access === "off" ? null : access;
+  }
+  return ctx.http.request<{ karta: KartaRecord }>({
+    method: "PATCH",
+    path: `/api/kartas/${encodeURIComponent(kartaId)}`,
+    headers: { "Idempotency-Key": randomUUID() },
+    body,
+  });
+}
+
+export async function kartasConfigure(ctx: CliContext, id: string, options: KartaConfigureOptions): Promise<string> {
+  const { karta } = await kartasConfigureData(ctx, id, options);
+  return karta.url
+    ? `Updated ${karta.name ?? karta.id}. Stable URL: ${karta.url}`
+    : `Updated ${karta.name ?? karta.id}. Stable URL is off.`;
+}
+
+// Retire a dharta. A REVERSIBLE archive, never a delete: the durable workspace
+// and its history survive untouched, and `dharta kartas restore` brings them
+// back. Erasing the underlying tree is a separate admin operation (RFC 0036
+// W7) - list-tidying must never destroy an end user's accumulated work.
+export async function kartasArchiveData(
+  ctx: CliContext,
+  id: string,
+): Promise<{ karta: KartaRecord }> {
+  const kartaId = normalizeNonBlank(id, "dharta id");
+  return ctx.http.request<{ karta: KartaRecord }>({
+    method: "DELETE",
+    path: `/api/kartas/${encodeURIComponent(kartaId)}`,
+    headers: { "Idempotency-Key": randomUUID() },
+  });
+}
+
+export async function kartasArchive(ctx: CliContext, id: string): Promise<string> {
+  const { karta } = await kartasArchiveData(ctx, id);
+  return (
+    `Archived ${karta.name ?? karta.id}. Its files and history are kept - ` +
+    `restore with: dharta kartas restore ${karta.id}`
+  );
+}
+
+export async function kartasRestoreData(
+  ctx: CliContext,
+  id: string,
+): Promise<{ karta: KartaRecord }> {
+  const kartaId = normalizeNonBlank(id, "dharta id");
+  return ctx.http.request<{ karta: KartaRecord }>({
+    method: "POST",
+    path: `/api/kartas/${encodeURIComponent(kartaId)}/restore`,
+    headers: { "Idempotency-Key": randomUUID() },
+  });
+}
+
+export async function kartasRestore(ctx: CliContext, id: string): Promise<string> {
+  const { karta } = await kartasRestoreData(ctx, id);
+  return karta.url
+    ? `Restored ${karta.name ?? karta.id}. Stable URL: ${karta.url}`
+    : `Restored ${karta.name ?? karta.id}.`;
+}
+
+export async function kartaMembersGrantData(
+  ctx: CliContext,
+  id: string,
+  email: string,
+  role: string,
+): Promise<{ member: KartaMember }> {
+  const kartaId = normalizeNonBlank(id, "dharta id");
+  const normalizedEmail = normalizeNonBlank(email, "person email");
+  const normalizedRole = normalizeRole(role);
+  return ctx.http.request<{ member: KartaMember }>({
+    method: "POST",
+    path: `/api/kartas/${encodeURIComponent(kartaId)}/members`,
+    headers: { "Idempotency-Key": randomUUID() },
+    body: { email: normalizedEmail, role: normalizedRole },
+  });
+}
+
+export async function kartaMembersGrant(ctx: CliContext, id: string, email: string, role: string): Promise<string> {
+  const { member } = await kartaMembersGrantData(ctx, id, email, role);
+  return `Granted ${member.email} ${member.role} access to karta ${id}.`;
+}
+
+export async function kartaMembersSetRoleData(
+  ctx: CliContext,
+  id: string,
+  membershipId: string,
+  role: string,
+): Promise<{ member: KartaMember }> {
+  const kartaId = normalizeNonBlank(id, "dharta id");
+  const memberId = normalizeNonBlank(membershipId, "dharta membership id");
+  const normalizedRole = normalizeRole(role);
+  return ctx.http.request<{ member: KartaMember }>({
+    method: "PATCH",
+    path: `/api/kartas/${encodeURIComponent(kartaId)}/members/${encodeURIComponent(memberId)}`,
+    headers: { "Idempotency-Key": randomUUID() },
+    body: { role: normalizedRole },
+  });
+}
+
+export async function kartaMembersSetRole(
+  ctx: CliContext,
+  id: string,
+  membershipId: string,
+  role: string,
+): Promise<string> {
+  const { member } = await kartaMembersSetRoleData(ctx, id, membershipId, role);
+  return `${member.email} is now a ${member.role} on karta ${id}.`;
+}
+
+export async function kartaMembersRevokeData(
+  ctx: CliContext,
+  id: string,
+  membershipId: string,
+): Promise<{ id: string; membership_id: string; revoked: true }> {
+  const kartaId = normalizeNonBlank(id, "dharta id");
+  const memberId = normalizeNonBlank(membershipId, "dharta membership id");
+  await ctx.http.request<void>({
+    method: "DELETE",
+    path: `/api/kartas/${encodeURIComponent(kartaId)}/members/${encodeURIComponent(memberId)}`,
+    headers: { "Idempotency-Key": randomUUID() },
+  });
+  return { id: kartaId, membership_id: memberId, revoked: true };
+}
+
+export async function kartaMembersRevoke(ctx: CliContext, id: string, membershipId: string): Promise<string> {
+  await kartaMembersRevokeData(ctx, id, membershipId);
+  return `Revoked dharta membership ${membershipId} from ${id}.`;
+}
+
+function normalizeAudience(audience: string): KartaAudience {
+  const normalized = normalizeNonBlank(audience, "karta access audience");
+  if ((DHARTA_AUDIENCES as readonly string[]).includes(normalized)) return normalized as KartaAudience;
+  const suggestion = closestChoice(normalized, DHARTA_AUDIENCES);
+  throw new Error(
+    `Unknown karta access ${normalized}. Allowed values: ${DHARTA_AUDIENCES.join(", ")}.` +
+      (suggestion ? ` Did you mean ${suggestion}?` : ""),
+  );
+}
+
+function normalizeRole(role: string): KartaRole {
+  const normalized = normalizeNonBlank(role, "karta member role");
+  if ((DHARTA_ROLES as readonly string[]).includes(normalized)) return normalized as KartaRole;
+  const suggestion = closestChoice(normalized, DHARTA_ROLES);
+  throw new Error(
+    `Unknown karta member role ${normalized}. Allowed roles: ${DHARTA_ROLES.join(", ")}.` +
+      (suggestion ? ` Did you mean ${suggestion}?` : ""),
+  );
+}
+
+function accessLabel(karta: KartaRecord): string {
+  if (karta.access_audience === "members") return "specific people (sign-in required)";
+  if (karta.access_audience === "anonymous") return "anyone with the link";
+  return "off";
+}
+
+// RFC 0073 - per-dharta environment variables.
+//
+// Addressed by (agent, karta) rather than a karta id alone: a Type 1 karta has
+// no `agent_instances` row and so no /api/kartas identity, and the same
+// end-user subject holds a DIFFERENT binding of the same name on every agent
+// they use. The :karta segment also accepts a named karta's vanity slug.
+export interface KartaEnvRecord {
+  name: string;
+  secret: boolean;
+  value?: string | null;
+  updated_at?: string;
+  updated_by?: string;
+}
+
+function envPath(agent: string, karta: string, name?: string): string {
+  const base = `/api/agents/${encodeURIComponent(agent)}/instances/${encodeURIComponent(karta)}/env`;
+  return name === undefined ? base : `${base}/${encodeURIComponent(name)}`;
+}
+
+export async function kartaEnvListData(
+  ctx: CliContext,
+  agent: string,
+  karta: string,
+): Promise<KartaEnvRecord[]> {
+  const agentSlug = normalizeNonBlank(agent, "agent slug");
+  const kartaId = normalizeNonBlank(karta, "dharta id");
+  const response = await ctx.http.request<{ env: KartaEnvRecord[] }>({
+    path: envPath(agentSlug, kartaId),
+  });
+  return response.env ?? [];
+}
+
+export async function kartaEnvList(ctx: CliContext, agent: string, karta: string): Promise<string> {
+  const env = await kartaEnvListData(ctx, agent, karta);
+  if (env.length === 0) return "No per-dharta environment variables set.";
+  return table(env.map((row) => ({
+    name: row.name,
+    // Secret values are never returned by the API; non-secret (--plain) values
+    // are masked here too so a routine list never prints a token to the
+    // terminal. Use `--json` for raw values. Shared with `dharta env list`.
+    value: maskEnvValue(row, false),
+    updated: row.updated_at ?? "—",
+    by: row.updated_by ?? "—",
+  })));
+}
+
+export async function kartaEnvSetData(
+  ctx: CliContext,
+  agent: string,
+  karta: string,
+  name: string,
+  value: string,
+  options: { secret?: boolean } = {},
+): Promise<KartaEnvRecord> {
+  const agentSlug = normalizeNonBlank(agent, "agent slug");
+  const kartaId = normalizeNonBlank(karta, "dharta id");
+  const varName = normalizeNonBlank(name, "variable name");
+  return ctx.http.request<KartaEnvRecord>({
+    method: "PUT",
+    path: envPath(agentSlug, kartaId, varName),
+    body: options.secret === undefined ? { value } : { value, secret: options.secret },
+  });
+}
+
+export async function kartaEnvSet(
+  ctx: CliContext,
+  agent: string,
+  karta: string,
+  name: string,
+  value: string,
+  options: { secret?: boolean } = {},
+): Promise<string> {
+  const row = await kartaEnvSetData(ctx, agent, karta, name, value, options);
+  return `Set ${row.name} on ${karta}.`;
+}
+
+export async function kartaEnvUnsetData(
+  ctx: CliContext,
+  agent: string,
+  karta: string,
+  name: string,
+): Promise<void> {
+  const agentSlug = normalizeNonBlank(agent, "agent slug");
+  const kartaId = normalizeNonBlank(karta, "dharta id");
+  const varName = normalizeNonBlank(name, "variable name");
+  await ctx.http.request<void>({ method: "DELETE", path: envPath(agentSlug, kartaId, varName) });
+}
+
+export async function kartaEnvUnset(
+  ctx: CliContext,
+  agent: string,
+  karta: string,
+  name: string,
+): Promise<string> {
+  await kartaEnvUnsetData(ctx, agent, karta, name);
+  return `Removed ${name} from ${karta}.`;
+}

package/src/commands/keys.ts

@@ -0,0 +1,206 @@
+import type { CliContext } from "../context.js";
+import { API_KEY_SCOPES, type ApiKeyScope } from "@dharta/sdk";
+import { randomUUID } from "node:crypto";
+import { fmtTs, table } from "../output.js";
+import { closestChoice, normalizeIsoTimestamp, normalizeNonBlank } from "../validators.js";
+import { formatScopes, SENSITIVE_API_KEY_SCOPES } from "./scopes.js";
+
+interface ListEnvelope<T> {
+  data: T[];
+}
+
+interface ApiKey {
+  id: string;
+  name: string;
+  prefix: string;
+  scopes: ApiKeyScope[];
+  mode?: string;
+  expires_at?: string | null;
+  created_at: string;
+  last_used_at: string | null;
+  revoked_at: string | null;
+}
+
+interface ApiKeyCreateResponse {
+  api_key: ApiKey;
+  secret: string;
+}
+
+export interface ApiKeyCreateOptions {
+  expiresAt?: string;
+}
+
+const MAX_FORCED_EXPIRY_MS = 90 * 24 * 60 * 60 * 1000;
+export async function keysListData(ctx: CliContext) {
+  try {
+    const res = await ctx.http.request<ListEnvelope<ApiKey>>({ path: "/api_keys" });
+    return res.data;
+  } catch (error) {
+    throw addKeysListScopeGuidance(error);
+  }
+}
+
+export async function keysList(ctx: CliContext): Promise<string> {
+  const keys = await keysListData(ctx);
+  if (keys.length === 0) return "No API keys. Create one with: dharta keys create <name> --scope agents:read";
+  return table(
+    keys.map((k) => ({
+      prefix: k.prefix,
+      name: k.name,
+      scopes: formatScopes(k.scopes, ","),
+      created: fmtTs(k.created_at),
+      last_used: fmtTs(k.last_used_at),
+      revoked: fmtTs(k.revoked_at),
+    })),
+  );
+}
+
+export async function keysCreateData(
+  ctx: CliContext,
+  name: string,
+  scopes: ApiKeyScope[],
+  opts: ApiKeyCreateOptions = {},
+) {
+  validateKeysCreateInput(name, scopes, opts);
+  const normalizedScopes = normalizeScopes(scopes);
+  const normalizedOpts = normalizeCreateOptions(normalizedScopes, opts);
+  const body: Record<string, unknown> = { name: normalizeKeyName(name), scopes: normalizedScopes };
+  if (normalizedOpts.expiresAt !== undefined) body.expires_at = normalizedOpts.expiresAt;
+  return ctx.http.request<ApiKeyCreateResponse>({
+    method: "POST",
+    path: "/api_keys",
+    body,
+    headers: { "Idempotency-Key": randomUUID() },
+  });
+}
+
+export async function keysCreate(
+  ctx: CliContext,
+  name: string,
+  scopes: ApiKeyScope[],
+  opts: ApiKeyCreateOptions = {},
+): Promise<string> {
+  const res = await keysCreateData(ctx, name, scopes, opts);
+  return [
+    `Created key ${res.api_key.prefix} (${res.api_key.id})`,
+    `Scopes: ${res.api_key.scopes.join(",")}`,
+    res.api_key.expires_at ? `Expires: ${res.api_key.expires_at}` : null,
+    "",
+    `Secret (shown once — store it now):`,
+    res.secret,
+  ].filter((line) => line !== null).join("\n");
+}
+
+export function validateKeysCreateInput(
+  name: string,
+  scopes: ApiKeyScope[],
+  opts: ApiKeyCreateOptions = {},
+): void {
+  normalizeKeyName(name);
+  normalizeCreateOptions(normalizeScopes(scopes), opts);
+}
+
+export async function keysRevokeData(
+  ctx: CliContext,
+  id: string,
+): Promise<{ id: string; revoked: boolean }> {
+  const normalizedId = normalizeNonBlank(id, "API key id");
+  await ctx.http.request<void>({
+    method: "DELETE",
+    path: `/api_keys/${encodeURIComponent(normalizedId)}`,
+    headers: { "Idempotency-Key": randomUUID() },
+  });
+  return { id: normalizedId, revoked: true };
+}
+
+export async function keysRevoke(ctx: CliContext, id: string): Promise<string> {
+  const res = await keysRevokeData(ctx, id);
+  return `Revoked ${res.id}.`;
+}
+
+export async function keysRenameData(
+  ctx: CliContext,
+  id: string,
+  name: string,
+): Promise<ApiKey> {
+  const normalizedId = normalizeNonBlank(id, "API key id");
+  const normalizedName = normalizeKeyName(name);
+  const res = await ctx.http.request<{ api_key: ApiKey }>({
+    method: "PATCH",
+    path: `/api_keys/${encodeURIComponent(normalizedId)}`,
+    body: { name: normalizedName },
+    headers: { "Idempotency-Key": randomUUID() },
+  });
+  return res.api_key;
+}
+
+export async function keysRename(ctx: CliContext, id: string, name: string): Promise<string> {
+  const key = await keysRenameData(ctx, id, name);
+  return `Renamed ${key.prefix} to ${key.name}.`;
+}
+
+function normalizeKeyName(name: string): string {
+  const normalized = name.trim();
+  if (!normalized) {
+    throw new Error("API key name cannot be blank.");
+  }
+  return normalized;
+}
+
+function normalizeScopes(scopes: ApiKeyScope[]): ApiKeyScope[] {
+  if (scopes.length === 0) {
+    throw new Error("Pass at least one --scope, e.g. --scope agents:read.");
+  }
+  const allowed = new Set<string>(API_KEY_SCOPES);
+  const normalized = scopes.map((scope) => normalizeNonBlank(scope, "API key scope") as ApiKeyScope);
+  const unknown = normalized.filter((scope) => !allowed.has(scope));
+  if (unknown.length > 0) {
+    const suggestion = unknown.length === 1 ? closestChoice(unknown[0]!, API_KEY_SCOPES) : null;
+    throw new Error(
+      `Unknown --scope ${unknown.join(", ")}. Allowed scopes: ${API_KEY_SCOPES.join(", ")}.` +
+        (suggestion ? ` Did you mean ${suggestion}?` : ""),
+    );
+  }
+  return normalized;
+}
+
+function normalizeCreateOptions(scopes: ApiKeyScope[], opts: ApiKeyCreateOptions): ApiKeyCreateOptions {
+  const normalized: ApiKeyCreateOptions = { ...opts };
+  if (opts.expiresAt !== undefined) {
+    normalized.expiresAt = normalizeIsoTimestamp(opts.expiresAt, "--expires-at");
+    if (new Date(normalized.expiresAt).getTime() <= Date.now()) {
+      throw new Error("--expires-at must be in the future.");
+    }
+  }
+
+  const forced = scopes.filter((scope) => SENSITIVE_API_KEY_SCOPES.has(scope));
+  if (forced.length === 0) return normalized;
+
+  if (normalized.expiresAt === undefined) {
+    throw new Error(
+      `Sensitive scopes require --expires-at within 90 days: ${forced.join(", ")}.`,
+    );
+  }
+  if (new Date(normalized.expiresAt).getTime() > Date.now() + MAX_FORCED_EXPIRY_MS) {
+    throw new Error("Sensitive scopes require --expires-at within 90 days.");
+  }
+  return normalized;
+}
+
+function addKeysListScopeGuidance(error: unknown): Error {
+  if (error instanceof Error) {
+    const status = (error as Error & { status?: unknown }).status;
+    if (
+      status === 403 &&
+      /scope/i.test(error.message) &&
+      /(keys:read|keys:write)/.test(error.message) &&
+      !error.message.includes("Listing API keys requires")
+    ) {
+      error.message +=
+        `${error.message.endsWith(".") ? "" : "."} ` +
+        "Listing API keys requires `keys:read` or `keys:write`.";
+    }
+    return error;
+  }
+  return new Error(String(error));
+}