@vellumai/assistant 0.4.46 → 0.4.49

package/src/cli/commands/oauth/apps.ts

@@ -0,0 +1,255 @@
+import type { Command } from "commander";
+
+import {
+  deleteApp,
+  getApp,
+  getAppByProviderAndClientId,
+  getMostRecentAppByProvider,
+  listApps,
+  upsertApp,
+} from "../../../oauth/oauth-store.js";
+import { getCliLogger } from "../../logger.js";
+import { shouldOutputJson, writeOutput } from "../../output.js";
+
+const log = getCliLogger("cli");
+
+/** Format an app row for output, converting timestamps to ISO strings. */
+function formatAppRow(row: {
+  id: string;
+  providerKey: string;
+  clientId: string;
+  createdAt: number;
+  updatedAt: number;
+}) {
+  return {
+    id: row.id,
+    providerKey: row.providerKey,
+    clientId: row.clientId,
+    createdAt: new Date(row.createdAt).toISOString(),
+    updatedAt: new Date(row.updatedAt).toISOString(),
+  };
+}
+
+export function registerAppCommands(oauth: Command): void {
+  const apps = oauth
+    .command("apps")
+    .description("Manage OAuth app registrations (client IDs and secrets)");
+
+  apps.addHelpText(
+    "after",
+    `
+Apps represent OAuth client registrations — a client_id and optional
+client_secret linked to a provider. Each provider can have multiple apps
+(e.g. different client IDs for different environments).
+
+Examples:
+  $ assistant oauth apps list
+  $ assistant oauth apps get --id <uuid>
+  $ assistant oauth apps get --provider integration:gmail
+  $ assistant oauth apps upsert --provider integration:gmail --client-id abc123
+  $ assistant oauth apps delete <id>`,
+  );
+
+  // ---------------------------------------------------------------------------
+  // apps list
+  // ---------------------------------------------------------------------------
+
+  apps
+    .command("list")
+    .description("List all OAuth app registrations")
+    .addHelpText(
+      "after",
+      `
+Returns all registered OAuth apps with their provider key, client ID, and
+timestamps. Output is an array of app objects.
+
+In JSON mode (--json), returns the array directly. In human mode, logs a
+summary count and prints the formatted list.
+
+Examples:
+  $ assistant oauth apps list
+  $ assistant oauth apps list --json`,
+    )
+    .action((_opts: unknown, cmd: Command) => {
+      try {
+        const rows = listApps().map(formatAppRow);
+
+        if (!shouldOutputJson(cmd)) {
+          log.info(`Found ${rows.length} app(s)`);
+        }
+
+        writeOutput(cmd, rows);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+
+  // ---------------------------------------------------------------------------
+  // apps get
+  // ---------------------------------------------------------------------------
+
+  apps
+    .command("get")
+    .description(
+      "Look up an OAuth app by ID, provider + client-id, or provider",
+    )
+    .option("--id <id>", "App ID (UUID)")
+    .option("--provider <key>", "Provider key (e.g. integration:gmail)")
+    .option("--client-id <id>", "OAuth client ID (requires --provider)")
+    .addHelpText(
+      "after",
+      `
+Three lookup modes are supported:
+
+  1. By app ID:
+     $ assistant oauth apps get --id <uuid>
+
+  2. By provider + client ID (exact match):
+     $ assistant oauth apps get --provider integration:gmail --client-id abc123
+
+  3. By provider only (returns the most recently created app):
+     $ assistant oauth apps get --provider integration:gmail
+
+At least --id or --provider must be specified.`,
+    )
+    .action(
+      (
+        opts: { id?: string; provider?: string; clientId?: string },
+        cmd: Command,
+      ) => {
+        try {
+          let row;
+
+          if (opts.id) {
+            row = getApp(opts.id);
+          } else if (opts.provider && opts.clientId) {
+            row = getAppByProviderAndClientId(opts.provider, opts.clientId);
+          } else if (opts.provider) {
+            row = getMostRecentAppByProvider(opts.provider);
+          } else {
+            writeOutput(cmd, {
+              ok: false,
+              error: "Provide --id, --provider, or --provider + --client-id",
+            });
+            process.exitCode = 1;
+            return;
+          }
+
+          if (!row) {
+            writeOutput(cmd, { ok: false, error: "App not found" });
+            process.exitCode = 1;
+            return;
+          }
+
+          writeOutput(cmd, formatAppRow(row));
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        }
+      },
+    );
+
+  // ---------------------------------------------------------------------------
+  // apps upsert
+  // ---------------------------------------------------------------------------
+
+  apps
+    .command("upsert")
+    .description("Create or return an existing OAuth app registration")
+    .requiredOption("--provider <key>", "Provider key (e.g. integration:gmail)")
+    .requiredOption("--client-id <id>", "OAuth client ID")
+    .option(
+      "--client-secret <secret>",
+      "OAuth client secret (stored in secure keychain)",
+    )
+    .addHelpText(
+      "after",
+      `
+Creates a new app registration or returns the existing one if an app with the
+same provider and client ID already exists. The client secret, if provided, is
+stored in the secure system keychain — not in the database.
+
+When an existing app is matched and a --client-secret is provided, the stored
+secret is updated. The app row itself is returned as-is.
+
+Examples:
+  $ assistant oauth apps upsert --provider integration:gmail --client-id abc123
+  $ assistant oauth apps upsert --provider integration:slack --client-id def456 --client-secret s3cret
+  $ assistant oauth apps upsert --provider integration:gmail --client-id abc123 --json`,
+    )
+    .action(
+      async (
+        opts: { provider: string; clientId: string; clientSecret?: string },
+        cmd: Command,
+      ) => {
+        try {
+          const row = await upsertApp(
+            opts.provider,
+            opts.clientId,
+            opts.clientSecret,
+          );
+
+          if (!shouldOutputJson(cmd)) {
+            log.info(`Upserted app: ${row.id} (provider: ${row.providerKey})`);
+          }
+
+          writeOutput(cmd, formatAppRow(row));
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        }
+      },
+    );
+
+  // ---------------------------------------------------------------------------
+  // apps delete <id>
+  // ---------------------------------------------------------------------------
+
+  apps
+    .command("delete <id>")
+    .description("Delete an OAuth app registration by ID")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  id   The app UUID to delete (as returned by "apps list" or "apps get")
+
+Permanently removes the app registration and its stored client secret from
+the keychain. Any OAuth connections that reference this app will no longer be
+able to refresh tokens.
+
+Exits with code 1 if the app ID is not found.
+
+Examples:
+  $ assistant oauth apps delete 550e8400-e29b-41d4-a716-446655440000
+  $ assistant oauth apps delete 550e8400-e29b-41d4-a716-446655440000 --json`,
+    )
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      try {
+        const deleted = await deleteApp(id);
+
+        if (!deleted) {
+          writeOutput(cmd, {
+            ok: false,
+            error: `App not found: ${id}`,
+          });
+          process.exitCode = 1;
+          return;
+        }
+
+        if (!shouldOutputJson(cmd)) {
+          log.info(`Deleted app: ${id}`);
+        }
+
+        writeOutput(cmd, { ok: true, id });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/commands/oauth/connections.ts

@@ -0,0 +1,299 @@
+import type { Command } from "commander";
+
+import {
+  disconnectOAuthProvider,
+  getConnection,
+  getConnectionByProvider,
+  listConnections,
+} from "../../../oauth/oauth-store.js";
+import { credentialKey } from "../../../security/credential-key.js";
+import { deleteSecureKeyAsync } from "../../../security/secure-keys.js";
+import { withValidToken } from "../../../security/token-manager.js";
+import {
+  assertMetadataWritable,
+  deleteCredentialMetadata,
+} from "../../../tools/credentials/metadata-store.js";
+import { getCliLogger } from "../../logger.js";
+import { shouldOutputJson, writeOutput } from "../../output.js";
+
+const log = getCliLogger("cli");
+
+/**
+ * Keys that may contain secrets in an OAuth token endpoint response.
+ * These are stripped from the `metadata` field before CLI output to prevent
+ * token leakage via shell history, logs, or agent transcript capture.
+ */
+const REDACTED_METADATA_KEYS = new Set([
+  "access_token",
+  "refresh_token",
+  "id_token",
+]);
+
+/** Recursively strip secret-bearing keys from a parsed metadata object. */
+function redactMetadata(obj: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (REDACTED_METADATA_KEYS.has(key)) {
+      result[key] = "[REDACTED]";
+    } else if (value && typeof value === "object" && !Array.isArray(value)) {
+      result[key] = redactMetadata(value as Record<string, unknown>);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+/** Parse stored JSON string fields and convert timestamps for a connection row. */
+function formatConnectionRow(row: ReturnType<typeof getConnection>) {
+  if (!row) return row;
+  const parsed = row.metadata ? JSON.parse(row.metadata) : null;
+  return {
+    ...row,
+    grantedScopes: row.grantedScopes ? JSON.parse(row.grantedScopes) : [],
+    metadata: parsed ? redactMetadata(parsed) : null,
+    hasRefreshToken: row.hasRefreshToken === 1,
+    createdAt: new Date(row.createdAt).toISOString(),
+    updatedAt: new Date(row.updatedAt).toISOString(),
+    expiresAt: row.expiresAt ? new Date(row.expiresAt).toISOString() : null,
+  };
+}
+
+export function registerConnectionCommands(oauth: Command): void {
+  const connections = oauth
+    .command("connections")
+    .description("Manage OAuth connections (active tokens and refresh state)");
+
+  connections.addHelpText(
+    "after",
+    `
+Connections represent active OAuth sessions — an access token bound to a
+provider through an app registration. Each connection tracks granted scopes,
+token expiry, refresh token availability, account info, and status.
+
+Examples:
+  $ assistant oauth connections list
+  $ assistant oauth connections list --provider integration:gmail
+  $ assistant oauth connections get --id <uuid>
+  $ assistant oauth connections get --provider integration:gmail
+  $ assistant oauth connections token integration:twitter`,
+  );
+
+  // ---------------------------------------------------------------------------
+  // connections list
+  // ---------------------------------------------------------------------------
+
+  connections
+    .command("list")
+    .description("List all OAuth connections")
+    .option(
+      "--provider <key>",
+      "Filter by provider key (e.g. integration:gmail)",
+    )
+    .addHelpText(
+      "after",
+      `
+Lists all OAuth connections, optionally filtered by provider key.
+
+Each connection shows its ID, provider, account info, granted scopes, token
+expiry, refresh token availability, and status.
+
+Examples:
+  $ assistant oauth connections list
+  $ assistant oauth connections list --provider integration:gmail`,
+    )
+    .action((opts: { provider?: string }, cmd: Command) => {
+      try {
+        const rows = listConnections(opts.provider).map(formatConnectionRow);
+
+        if (!shouldOutputJson(cmd)) {
+          log.info(`Found ${rows.length} connection(s)`);
+        }
+
+        writeOutput(cmd, rows);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+
+  // ---------------------------------------------------------------------------
+  // connections get
+  // ---------------------------------------------------------------------------
+
+  connections
+    .command("get")
+    .description("Look up an OAuth connection by ID or provider")
+    .option("--id <id>", "Connection ID (UUID)")
+    .option(
+      "--provider <key>",
+      "Provider key (returns most recent active connection)",
+    )
+    .addHelpText(
+      "after",
+      `
+Two lookup modes are supported:
+
+  1. By connection ID:
+     $ assistant oauth connections get --id <uuid>
+
+  2. By provider (returns the most recent active connection):
+     $ assistant oauth connections get --provider integration:gmail
+
+At least --id or --provider must be specified.`,
+    )
+    .action((opts: { id?: string; provider?: string }, cmd: Command) => {
+      try {
+        let row;
+
+        if (opts.id) {
+          row = getConnection(opts.id);
+        } else if (opts.provider) {
+          row = getConnectionByProvider(opts.provider);
+        } else {
+          writeOutput(cmd, {
+            ok: false,
+            error: "Provide --id or --provider",
+          });
+          process.exitCode = 1;
+          return;
+        }
+
+        if (!row) {
+          writeOutput(cmd, { ok: false, error: "Connection not found" });
+          process.exitCode = 1;
+          return;
+        }
+
+        writeOutput(cmd, formatConnectionRow(row));
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+
+  // ---------------------------------------------------------------------------
+  // connections token <provider-key>
+  // ---------------------------------------------------------------------------
+
+  connections
+    .command("token <provider-key>")
+    .description(
+      "Print a valid OAuth access token for a provider, refreshing if expired",
+    )
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  provider-key   Provider key (e.g. integration:gmail, integration:twitter)
+
+Returns a valid OAuth access token for the given provider. If the stored token
+is expired or near-expiry, it is refreshed automatically before being returned.
+
+In human mode, prints the bare token to stdout (suitable for shell substitution).
+In JSON mode (--json), prints {"ok": true, "token": "..."}.
+
+Exits with code 1 if no access token exists or refresh fails.
+
+Examples:
+  $ assistant oauth connections token integration:twitter
+  $ assistant oauth connections token integration:gmail --json`,
+    )
+    .action(async (providerKey: string, _opts: unknown, cmd: Command) => {
+      try {
+        const token = await withValidToken(providerKey, async (t) => t);
+        if (shouldOutputJson(cmd)) {
+          writeOutput(cmd, { ok: true, token });
+        } else {
+          process.stdout.write(token + "\n");
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+
+  // ---------------------------------------------------------------------------
+  // connections disconnect <provider-key>
+  // ---------------------------------------------------------------------------
+
+  connections
+    .command("disconnect <provider-key>")
+    .description(
+      "Disconnect an OAuth integration and remove all associated credentials",
+    )
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  provider-key   The full provider key (e.g. integration:gmail, integration:slack)
+
+Removes the OAuth connection, tokens, and any legacy credential metadata for
+the provider. The <provider-key> argument is the full provider key as-is — it
+is not parsed through service:field splitting.
+
+Legacy credential keys for common fields (access_token, refresh_token,
+client_id, client_secret) are also cleaned up if present.
+
+Examples:
+  $ assistant oauth connections disconnect integration:gmail
+  $ assistant oauth connections disconnect integration:slack`,
+    )
+    .action(async (providerKey: string, _opts: unknown, cmd: Command) => {
+      try {
+        assertMetadataWritable();
+
+        let cleanedUp = false;
+
+        // 1. Disconnect the OAuth connection (new-format keys + connection row)
+        const oauthResult = await disconnectOAuthProvider(providerKey);
+        if (oauthResult === "error") {
+          writeOutput(cmd, {
+            ok: false,
+            error: `Failed to disconnect OAuth provider "${providerKey}" — please try again`,
+          });
+          process.exitCode = 1;
+          return;
+        }
+        if (oauthResult === "disconnected") cleanedUp = true;
+
+        // 2. Clean up legacy credential keys for common fields
+        const legacyFields = [
+          "access_token",
+          "refresh_token",
+          "client_id",
+          "client_secret",
+        ];
+        for (const field of legacyFields) {
+          const key = credentialKey(providerKey, field);
+          const result = await deleteSecureKeyAsync(key);
+          if (result === "deleted") cleanedUp = true;
+
+          const metaDeleted = deleteCredentialMetadata(providerKey, field);
+          if (metaDeleted) cleanedUp = true;
+        }
+
+        if (!cleanedUp) {
+          writeOutput(cmd, {
+            ok: false,
+            error: `No OAuth connection or credentials found for "${providerKey}"`,
+          });
+          process.exitCode = 1;
+          return;
+        }
+
+        writeOutput(cmd, { ok: true, service: providerKey });
+
+        if (!shouldOutputJson(cmd)) {
+          log.info(`Disconnected ${providerKey}`);
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/commands/oauth/index.ts

@@ -0,0 +1,52 @@
+import type { Command } from "commander";
+
+import { registerAppCommands } from "./apps.js";
+import { registerConnectionCommands } from "./connections.js";
+import { registerProviderCommands } from "./providers.js";
+
+export function registerOAuthCommand(program: Command): void {
+  const oauth = program
+    .command("oauth")
+    .description("Manage OAuth providers, apps, connections, and tokens")
+    .option("--json", "Machine-readable compact JSON output");
+
+  oauth.addHelpText(
+    "after",
+    `
+The oauth command group manages the full OAuth lifecycle:
+
+  providers   Protocol-level configurations (auth URLs, scopes, endpoints)
+  apps        Client credentials (client ID / secret pairs)
+  connections Active token grants per provider (list, get, token)
+
+Providers are seeded on startup for built-in integrations. Apps and connections
+are created during the OAuth authorization flow or can be managed manually via
+their respective subcommands.
+
+Examples:
+  $ assistant oauth connections token integration:twitter
+  $ assistant oauth connections list
+  $ assistant oauth connections get --provider integration:gmail
+  $ assistant oauth providers list
+  $ assistant oauth providers get integration:gmail
+  $ assistant oauth providers register --provider-key custom:myapi --auth-url https://example.com/auth --token-url https://example.com/token`,
+  );
+
+  // ---------------------------------------------------------------------------
+  // providers — subcommand group
+  // ---------------------------------------------------------------------------
+
+  registerProviderCommands(oauth);
+
+  // ---------------------------------------------------------------------------
+  // apps — subcommand group
+  // ---------------------------------------------------------------------------
+
+  registerAppCommands(oauth);
+
+  // ---------------------------------------------------------------------------
+  // connections — subcommand group (includes token)
+  // ---------------------------------------------------------------------------
+
+  registerConnectionCommands(oauth);
+}