@cardstack/boxel-cli 0.12.0-unstable.12 → 0.12.0-unstable.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardstack/boxel-cli",
-  "version": "0.12.0-unstable.12",
+  "version": "0.12.0-unstable.13",
   "license": "MIT",
   "description": "CLI tools for Boxel workspace management",
   "main": "./dist/index.js",

package/src/commands/keys/index.ts

@@ -12,6 +12,7 @@ import {
   keysClients,
   keysConnect,
   keysDelete,
+  keysLimits,
   keysList,
   keysReplace,
   keysShare,
@@ -19,8 +20,10 @@ import {
   keysShow,
   keysSwap,
   keysUnshare,
+  keysUsage,
   runKeysCommand,
   signInToManageKeys,
+  type LimitsOptions,
 } from './manage.ts';
 import {
   keysApprove,
@@ -366,6 +369,39 @@ export function registerKeysCommand(program: Command): void {
       runKeysCommand(options.json, () => keysShares(options)),
     );
 
+  keys
+    .command('limits')
+    .description(
+      "Show or set the limits on how much of one of your keys calls from cards, the AI assistant and the CLI may spend: on a personal key, or with --realm on your share of one there. Each limit takes a number, or default for the platform's. Without a limit to change, shows the limits in force",
+    )
+    .argument('<name>', 'Your key, or with --realm the label of the share')
+    .option('--realm <url>', 'The realm the share is in')
+    .option(
+      '--rate <burst>/<refill>',
+      'Per caller: how many calls at once, and how many a minute refill, such as 25/15 (default for both puts them back)',
+    )
+    .option('--daily <n>', 'Calls a UTC day, across every caller')
+    .option(
+      '--monthly <n>',
+      'Calls a UTC month, across every caller (default: 30 daily budgets)',
+    )
+    .option('--json', 'Output JSON')
+    .action((name: string, options: LimitsOptions) =>
+      runKeysCommand(options.json, () => keysLimits(name, options)),
+    );
+
+  keys
+    .command('usage')
+    .description(
+      "Show what one of your keys has served: this UTC day's and month's calls against its budgets, its last use, top callers, refusals by reason and the vendor's answers. With --realm, a share in that realm, for any of the realm's direct writers",
+    )
+    .argument('<name>', 'Your key, or with --realm the label of the share')
+    .option('--realm <url>', 'The realm the share is in')
+    .option('--json', 'Output JSON')
+    .action((name: string, options: { realm?: string; json?: boolean }) =>
+      runKeysCommand(options.json, () => keysUsage(name, options)),
+    );
+
   keys
     .command('clients')
     .description(

package/src/commands/keys/manage.ts

@@ -29,13 +29,16 @@ import {
   addUserKey,
   canonicalRealmUrl,
   deleteUserKey,
+  findShare,
   findUserKey,
+  getKeyUsage,
   listConnectableClients,
   listOwnShares,
   listRealmShares,
   listUserKeys,
   realmOpensToAnonymous,
   replaceUserKey,
+  setKeyLimits,
   setUserKeyAnonymousUse,
   shareUserKey,
   completeOAuthConnect,
@@ -43,7 +46,10 @@ import {
   swapKeyIntoShare,
   unshareUserKey,
   type ConnectableClient,
+  type KeyLimitChanges,
+  type KeyLimits,
   type KeyShare,
+  type KeyUsage,
   type OAuthClientSettings,
   type OAuthConnectOutcome,
   type ServiceAccountDetails,
@@ -55,12 +61,14 @@ import { finishInSecureWindow, windowTimeout } from './approve.ts';
 // put them into realms. Keys belong to the user, so only the share commands
 // name a realm.
 //
-// Reading (`list`, `show`, `shares`, `clients`) and unsharing use the
-// profile's ordinary realm-server session. A change that stores or hands out
-// a key (`add`, `replace`, `delete`, `share`, `swap`, `connect`) takes a key
-// write ticket for that change, which only a session signed in on the secure
-// origin can mint, so those commands first make sure the profile holds one,
-// opening the secure window's sign-in in the browser when it doesn't.
+// Reading (`list`, `show`, `shares`, `clients`, `usage`, and `limits` with
+// nothing to change) and unsharing use the profile's ordinary realm-server
+// session. A change that stores or hands out a key (`add`, `replace`,
+// `delete`, `share`, `swap`, `connect`) takes a key write ticket for that
+// change, which only a session signed in on the secure origin can mint, so
+// those commands first make sure the profile holds one, opening the secure
+// window's sign-in in the browser when it doesn't. Changing a key's limits
+// takes that session too, with no ticket.
 //
 // A key's value is typed at a masked prompt or read with `--stdin` or
 // `--key-file`, never taken as an argument, and nothing prints one. A refusal
@@ -1017,6 +1025,206 @@ export async function keysShares(
   return shares;
 }
 
+export interface LimitsOptions {
+  realm?: string;
+  // `<burst>/<refill per minute>`; either side may be `default`.
+  rate?: string;
+  daily?: string;
+  monthly?: string;
+  json?: boolean;
+}
+
+// A limit as typed: a number, or `default` for the platform's default. The
+// realm server says which numbers a limit takes.
+function limitValue(option: string, value: string): number | null {
+  if (value.trim().toLowerCase() === 'default') {
+    return null;
+  }
+  let number = Number(value);
+  if (value.trim() === '' || !Number.isFinite(number)) {
+    throw new Error(`${option} is a number, or default`);
+  }
+  return number;
+}
+
+function limitChanges(options: LimitsOptions): KeyLimitChanges {
+  let changes: KeyLimitChanges = {};
+  if (options.rate !== undefined) {
+    // A bare `default` puts both halves back, as `--daily default` does its one.
+    let parts =
+      options.rate.trim().toLowerCase() === 'default'
+        ? ['default', 'default']
+        : options.rate.split('/');
+    if (parts.length !== 2) {
+      throw new Error(
+        '--rate is <burst>/<refill per minute>, such as 25/15; either may be default, or default for both',
+      );
+    }
+    changes.rateBurst = limitValue('--rate burst', parts[0]!);
+    changes.rateRefillPerMinute = limitValue('--rate refill', parts[1]!);
+  }
+  if (options.daily !== undefined) {
+    changes.dailyBudget = limitValue('--daily', options.daily);
+  }
+  if (options.monthly !== undefined) {
+    changes.monthlyBudget = limitValue('--monthly', options.monthly);
+  }
+  return changes;
+}
+
+function printLimits(what: string, limits: KeyLimits): void {
+  console.log(`Limits on ${what}:`);
+  console.log(
+    `  rate: ${limits.rateBurst} calls at once per caller, refilled at ${limits.rateRefillPerMinute} a minute`,
+  );
+  console.log(`  daily budget: ${limits.dailyBudget} calls`);
+  console.log(`  monthly budget: ${limits.monthlyBudget} calls`);
+}
+
+// A share named by its label with `--realm`, or else one of the user's own
+// keys by name.
+async function limitedTarget(
+  ctx: Context,
+  token: string,
+  name: string,
+  realm: string | undefined,
+): Promise<{
+  what: string;
+  target: { shareId: string } | { keyId: string };
+  limits: KeyLimits | undefined;
+}> {
+  if (realm) {
+    let share = await findShare(ctx.realmServerUrl, token, {
+      realm,
+      label: name,
+    });
+    return {
+      what: `${share.label} in ${share.realm}`,
+      target: { shareId: share.id },
+      limits: share.limits,
+    };
+  }
+  let key = await findUserKey(ctx.realmServerUrl, token, name);
+  return { what: key.name, target: { keyId: key.id }, limits: key.limits };
+}
+
+// Shows or sets the limits on how much of a key interactive calls may spend:
+// on a personal key, or with `--realm` on a share of one in that realm. Only
+// the key's owner sets them, with a session signed in on the secure origin;
+// a realm's other direct writers can read a share's but are refused changing
+// them, by the realm server. Without a change, prints the limits in force.
+export async function keysLimits(
+  name: string,
+  options: LimitsOptions & KeysCommandDeps,
+): Promise<KeyLimits> {
+  let ctx = context(options.json, options);
+  let changes = limitChanges(options);
+  let changing = Object.keys(changes).length > 0;
+  let token = changing ? await secureToken(ctx) : await ordinaryToken(ctx);
+  let {
+    what,
+    target,
+    limits: current,
+  } = await limitedTarget(ctx, token, name, options.realm);
+  let limits = changing
+    ? await setKeyLimits(ctx.realmServerUrl, token, target, changes)
+    : current;
+  if (!limits) {
+    throw new Error(`The realm server didn't list the limits on ${what}`);
+  }
+  emit(ctx, limits, () => {
+    if (changing) {
+      console.log(`${FG_GREEN}Set the limits on ${what}.${RESET}`);
+    }
+    printLimits(what, limits);
+  });
+  return limits;
+}
+
+// The realm server names a caller only to someone who may see them in the
+// realm: one the reader can't see comes `withheld`, without a name, and a
+// call with no session comes without a name too.
+function callerName(
+  ctx: Context,
+  { caller, withheld }: { caller: string | null; withheld?: boolean },
+): string {
+  if (withheld) {
+    return "someone you can't see in the realm";
+  }
+  return caller === null
+    ? 'anonymous'
+    : caller === ctx.matrixUserId
+      ? 'you'
+      : caller;
+}
+
+function printBudget(label: string, use: KeyUsage['budgets']['day']): void {
+  console.log(
+    `  ${label}: ${use.used} of ${use.budget} calls ${DIM}(resets ${use.resetsAt})${RESET}`,
+  );
+}
+
+function printUsage(ctx: Context, what: string, usage: KeyUsage): void {
+  console.log(`Usage of ${what}:`);
+  printBudget('today', usage.budgets.day);
+  printBudget('this month', usage.budgets.month);
+  console.log(`  calls since ${usage.since}: ${usage.calls}`);
+  if (usage.lastUse) {
+    let { at, operation, outcome } = usage.lastUse;
+    console.log(
+      `  last use: ${at}, ${operation} by ${callerName(ctx, usage.lastUse)} (${outcome})`,
+    );
+  } else {
+    console.log('  last use: never');
+  }
+  if (usage.topCallers.length > 0) {
+    console.log('  top callers:');
+    for (let entry of usage.topCallers) {
+      console.log(`    ${callerName(ctx, entry)}: ${entry.calls}`);
+    }
+  }
+  if (usage.refusals.length > 0) {
+    console.log('  refusals:');
+    for (let { code, count } of usage.refusals) {
+      console.log(`    ${code}: ${count}`);
+    }
+  }
+  if (usage.vendorOutcomes.length > 0) {
+    console.log('  vendor answers:');
+    for (let { status, count, outcome } of usage.vendorOutcomes) {
+      console.log(`    ${status}${outcome ? ` (${outcome})` : ''}: ${count}`);
+    }
+  }
+  if (usage.grants.length > 0) {
+    console.log('  grants:');
+    for (let grant of usage.grants) {
+      let state =
+        grant.state === 'rejected'
+          ? `${FG_RED}rejected${RESET}${grant.rejectedAt ? ` ${grant.rejectedAt}` : ''}`
+          : grant.state;
+      console.log(`    ${grant.destination}: ${state}`);
+    }
+  }
+  printLimits(what, usage.limits);
+}
+
+// What a share or a personal key has served: its budgets' use this UTC day
+// and month, its last use, top callers, refusals by reason, the vendor's
+// answers and its grants. A personal key's usage is for its owner; a share's,
+// named by its label with `--realm`, for the realm's direct writers. Reading
+// needs no secure session.
+export async function keysUsage(
+  name: string,
+  options: { realm?: string; json?: boolean } & KeysCommandDeps,
+): Promise<KeyUsage> {
+  let ctx = context(options.json, options);
+  let token = await ordinaryToken(ctx);
+  let { what, target } = await limitedTarget(ctx, token, name, options.realm);
+  let usage = await getKeyUsage(ctx.realmServerUrl, token, target);
+  emit(ctx, usage, () => printUsage(ctx, what, usage));
+  return usage;
+}
+
 // How `connect --client` names a client: `platform:<name>` for one of
 // Boxel's own, a share's label for one shared into the realm given with
 // `--realm`, and otherwise the name of one of the user's own client keys.

package/src/lib/user-keys.ts

@@ -95,6 +95,8 @@ export interface UserKeyMetadata {
   oauth?: OAuthKeyDescription;
   // Only a google-service-account key has one.
   serviceAccount?: ServiceAccountDetails;
+  // The limits in force, defaults filled in.
+  limits?: KeyLimits;
   createdAt: string;
   updatedAt: string;
   // Whether its owner lets people who aren't signed in use it, wherever a
@@ -118,6 +120,9 @@ export interface KeyShare {
   suspensionReason: string | null;
   suspendedBy: string | null;
   suspendedAt: string | null;
+  // The limits in force, defaults filled in; listed for the key's owner and
+  // the realm's direct writers.
+  limits?: KeyLimits;
   createdAt: string;
   updatedAt: string;
   // In a realm's listing: the operations the share is approved for there,
@@ -125,6 +130,22 @@ export interface KeyShare {
   operations?: KeyShareOperation[];
 }
 
+// How much of a key interactive calls may spend: a token bucket per caller
+// (`rateBurst` calls at once, refilled at `rateRefillPerMinute`) and the calls
+// the share or key serves in a UTC day and month, across every caller.
+export interface KeyLimits {
+  rateBurst: number;
+  rateRefillPerMinute: number;
+  dailyBudget: number;
+  monthlyBudget: number;
+}
+
+// A change to some of a key's limits: a limit left out keeps what it was, and
+// null puts it back to the platform's default.
+export type KeyLimitChanges = Partial<{
+  [limit in keyof KeyLimits]: number | null;
+}>;
+
 export interface KeyShareOperation {
   bindingId: string;
   type: { module: string; name: string };
@@ -135,6 +156,50 @@ export interface KeyShareOperation {
   destination?: string;
 }
 
+// What a share or a personal key has served, as the realm server records it.
+// The counts cover `since` (the start of the UTC month) until now; the
+// budgets' `used` is what the limits count, interactive calls charged this
+// UTC day and month.
+export interface KeyUsage {
+  id: string;
+  limits: KeyLimits;
+  budgets: {
+    day: KeyBudgetUse;
+    month: KeyBudgetUse;
+  };
+  since: string;
+  calls: number;
+  lastUse: {
+    at: string;
+    caller: string | null;
+    operation: string;
+    outcome: 'sent' | 'refused' | 'failed';
+    // Set when the caller is someone the reader can't see in the realm.
+    withheld?: boolean;
+  } | null;
+  // A null caller is a call with no session; one marked `withheld` is every
+  // caller the reader can't see in the realm, counted together.
+  topCallers: { caller: string | null; calls: number; withheld?: boolean }[];
+  refusals: { code: string; count: number }[];
+  vendorOutcomes: { status: number; count: number; outcome?: string }[];
+  grants: {
+    id: string;
+    host: string;
+    destination: string;
+    state: 'active' | 'rejected';
+    rejectedAt: string | null;
+    lastForbiddenAt: string | null;
+  }[];
+  // Whether the reader may change the limits: only the key's owner may.
+  canEditLimits: boolean;
+}
+
+export interface KeyBudgetUse {
+  used: number;
+  budget: number;
+  resetsAt: string;
+}
+
 export interface KeyWriteTarget {
   action: KeyWriteAction;
   keyId?: string;
@@ -629,3 +694,69 @@ export async function completeOAuthConnect(
   );
   return json.data.attributes;
 }
+
+// The user's own share labelled `label` in `realm`, or else the realm's share
+// of that label, for a direct writer of the realm to read or to be refused
+// changing.
+export async function findShare(
+  realmServerUrl: string,
+  token: string,
+  { realm, label }: { realm: string; label: string },
+  fetchFn: FetchFn = fetch,
+): Promise<KeyShare> {
+  let canonical = canonicalRealmUrl(realm);
+  let own = (await listOwnShares(realmServerUrl, token, {}, fetchFn)).find(
+    (share) => share.realm === canonical && share.label === label,
+  );
+  if (own) {
+    return own;
+  }
+  return findByLabel(
+    await listRealmShares(realmServerUrl, token, realm, fetchFn),
+    realm,
+    label,
+  );
+}
+
+// Sets some of a share's or a personal key's limits, which only the key's
+// owner may, with a session signed in on the secure origin. Answers the
+// limits in force afterwards, defaults filled in.
+export async function setKeyLimits(
+  realmServerUrl: string,
+  token: string,
+  target: { shareId: string } | { keyId: string },
+  changes: KeyLimitChanges,
+  fetchFn: FetchFn = fetch,
+): Promise<KeyLimits> {
+  let path =
+    'shareId' in target
+      ? `_key-shares/${encodeURIComponent(target.shareId)}/limits`
+      : `_user-keys/${encodeURIComponent(target.keyId)}/limits`;
+  let json = await realmServerRequest(realmServerUrl, path, {
+    method: 'PUT',
+    token,
+    fetchFn,
+    body: { data: { type: 'key-limits', attributes: changes } },
+  });
+  return json.data.attributes as KeyLimits;
+}
+
+// What a share or a personal key has served. A share's usage is for the
+// realm's direct writers, a personal key's for its owner; anyone else is
+// answered 404, as for no such share or key.
+export async function getKeyUsage(
+  realmServerUrl: string,
+  token: string,
+  target: { shareId: string } | { keyId: string },
+  fetchFn: FetchFn = fetch,
+): Promise<KeyUsage> {
+  let path =
+    'shareId' in target
+      ? `_key-shares/${encodeURIComponent(target.shareId)}/usage`
+      : `_user-keys/${encodeURIComponent(target.keyId)}/usage`;
+  let json = await realmServerRequest(realmServerUrl, path, {
+    token,
+    fetchFn,
+  });
+  return fromResource<KeyUsage>(json.data);
+}