@vellumai/assistant 0.4.48 → 0.4.49

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);
+}

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

@@ -0,0 +1,242 @@
+import { type Command, InvalidArgumentError } from "commander";
+
+import {
+  getProvider,
+  listProviders,
+  registerProvider,
+} from "../../../oauth/oauth-store.js";
+import { getCliLogger } from "../../logger.js";
+import { shouldOutputJson, writeOutput } from "../../output.js";
+
+const log = getCliLogger("cli");
+
+/** Parse stored JSON string fields into their native types. */
+function parseProviderRow(row: ReturnType<typeof getProvider>) {
+  if (!row) return row;
+  return {
+    ...row,
+    defaultScopes: row.defaultScopes ? JSON.parse(row.defaultScopes) : [],
+    scopePolicy: row.scopePolicy ? JSON.parse(row.scopePolicy) : {},
+    extraParams: row.extraParams ? JSON.parse(row.extraParams) : null,
+    createdAt: new Date(row.createdAt).toISOString(),
+    updatedAt: new Date(row.updatedAt).toISOString(),
+  };
+}
+
+export function registerProviderCommands(oauth: Command): void {
+  const providers = oauth
+    .command("providers")
+    .description(
+      "Manage OAuth provider configurations (auth URLs, scopes, endpoints)",
+    );
+
+  providers.addHelpText(
+    "after",
+    `
+Providers define the protocol-level configuration for an OAuth integration:
+authorization URL, token URL, default scopes, and other endpoint details.
+
+They are seeded on startup for built-in integrations (e.g. Gmail, Twitter,
+Slack) but can also be registered dynamically via the "register" subcommand.
+
+Each provider is identified by a provider key (e.g. "integration:gmail").`,
+  );
+
+  // ---------------------------------------------------------------------------
+  // providers list
+  // ---------------------------------------------------------------------------
+
+  providers
+    .command("list")
+    .description("List all registered OAuth providers")
+    .option(
+      "--provider-key <key>",
+      'Filter by provider key substring (case-insensitive). Comma-separated values are OR\'d (e.g. "gmail,google")',
+    )
+    .addHelpText(
+      "after",
+      `
+Returns registered OAuth providers, including both built-in providers
+seeded at startup and any dynamically registered via "providers register".
+
+When --provider-key is specified, only providers whose key contains the
+given substring (case-insensitive) are returned. Multiple substrings can
+be OR'd together using commas (e.g. "gmail,google" matches any provider
+whose key contains "gmail" OR "google"). Without the flag, all providers
+are listed.
+
+Each provider row includes its key, auth URL, token URL, default scopes,
+and configuration timestamps.
+
+Examples:
+  $ assistant oauth providers list
+  $ assistant oauth providers list --provider-key gmail
+  $ assistant oauth providers list --provider-key "gmail,google"
+  $ assistant oauth providers list --provider-key slack --json`,
+    )
+    .action((opts: { providerKey?: string }, cmd: Command) => {
+      try {
+        let rows = listProviders().map(parseProviderRow);
+
+        if (opts.providerKey) {
+          const needles = opts.providerKey
+            .split(",")
+            .map((n) => n.trim().toLowerCase())
+            .filter(Boolean);
+          rows = rows.filter(
+            (r) =>
+              r &&
+              needles.some((needle) =>
+                r.providerKey.toLowerCase().includes(needle),
+              ),
+          );
+        }
+
+        if (!shouldOutputJson(cmd)) {
+          log.info(`Found ${rows.length} provider(s)`);
+        }
+
+        writeOutput(cmd, rows);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+
+  // ---------------------------------------------------------------------------
+  // providers get <provider-key>
+  // ---------------------------------------------------------------------------
+
+  providers
+    .command("get <provider-key>")
+    .description("Show details of a specific OAuth provider")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  provider-key   The full provider key (e.g. "integration:gmail").
+                 Must match the key used during registration or seeding.
+
+Returns the full provider configuration including auth URL, token URL,
+default scopes, scope policy, and extra parameters. Exits with code 1
+if the provider key is not found.
+
+Examples:
+  $ assistant oauth providers get integration:gmail
+  $ assistant oauth providers get integration:twitter --json`,
+    )
+    .action((providerKey: string, _opts: unknown, cmd: Command) => {
+      try {
+        const row = getProvider(providerKey);
+
+        if (!row) {
+          writeOutput(cmd, {
+            ok: false,
+            error: `Provider not found: ${providerKey}`,
+          });
+          process.exitCode = 1;
+          return;
+        }
+
+        writeOutput(cmd, parseProviderRow(row));
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+
+  // ---------------------------------------------------------------------------
+  // providers register
+  // ---------------------------------------------------------------------------
+
+  providers
+    .command("register")
+    .description("Register a new OAuth provider configuration")
+    .requiredOption("--provider-key <key>", "Provider key")
+    .requiredOption("--auth-url <url>", "Authorization endpoint URL")
+    .requiredOption("--token-url <url>", "Token endpoint URL")
+    .option("--base-url <url>", "API base URL")
+    .option("--userinfo-url <url>", "Userinfo endpoint URL")
+    .option("--scopes <scopes>", "Comma-separated default scopes")
+    .option("--token-auth-method <method>", "Token endpoint auth method")
+    .option("--callback-transport <transport>", "Callback transport")
+    .option("--loopback-port <port>", "Loopback port", (value: string) => {
+      const port = parseInt(value, 10);
+      if (isNaN(port) || port <= 0 || port > 65535) {
+        throw new InvalidArgumentError(
+          "Port must be a number between 1 and 65535",
+        );
+      }
+      return port;
+    })
+    .addHelpText(
+      "after",
+      `
+Arguments (via options):
+  --provider-key        Unique identifier for this provider (e.g. "integration:custom-service").
+                        Must not collide with an existing provider key.
+  --auth-url            The OAuth authorization endpoint URL.
+  --token-url           The OAuth token endpoint URL.
+  --base-url            Optional API base URL for the service.
+  --userinfo-url        Optional OpenID Connect userinfo endpoint.
+  --scopes              Comma-separated list of default scopes (e.g. "read,write,profile").
+  --token-auth-method   How the client authenticates at the token endpoint
+                        (e.g. "client_secret_post", "client_secret_basic").
+  --callback-transport  Transport method for the OAuth callback.
+  --loopback-port       Port number for the local loopback callback server (1-65535).
+
+Registers a new OAuth provider configuration in the local store. This is
+used for custom integrations not covered by the built-in provider seeds.
+On success, returns the full provider row including generated timestamps.
+
+Examples:
+  $ assistant oauth providers register \\
+      --provider-key integration:custom-api \\
+      --auth-url https://custom-api.example.com/oauth/authorize \\
+      --token-url https://custom-api.example.com/oauth/token
+  $ assistant oauth providers register \\
+      --provider-key integration:my-service \\
+      --auth-url https://my-service.com/auth \\
+      --token-url https://my-service.com/token \\
+      --scopes read,write --json`,
+    )
+    .action(
+      (
+        opts: {
+          providerKey: string;
+          authUrl: string;
+          tokenUrl: string;
+          baseUrl?: string;
+          userinfoUrl?: string;
+          scopes?: string;
+          tokenAuthMethod?: string;
+          callbackTransport?: string;
+          loopbackPort?: number;
+        },
+        cmd: Command,
+      ) => {
+        try {
+          const row = registerProvider({
+            providerKey: opts.providerKey,
+            authUrl: opts.authUrl,
+            tokenUrl: opts.tokenUrl,
+            baseUrl: opts.baseUrl,
+            userinfoUrl: opts.userinfoUrl,
+            defaultScopes: opts.scopes ? opts.scopes.split(",") : [],
+            scopePolicy: {},
+            tokenEndpointAuthMethod: opts.tokenAuthMethod,
+            callbackTransport: opts.callbackTransport,
+            loopbackPort: opts.loopbackPort,
+          });
+
+          writeOutput(cmd, parseProviderRow(row));
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        }
+      },
+    );
+}