feat(security): add clerk security audit, fix, and checks

.changeset/security-recommendations.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk security`: `audit` grades an instance against Clerk's security recommendations, `fix` applies them as one config patch, and `checks` lists the catalog. Agent mode gets the report as JSON with the exact patch per finding.

README.md

@@ -88,6 +88,7 @@ Commands:
   link             [options]                      Link this project to a Clerk application
   mcp                                             Manage the Clerk remote MCP server connection for AI editors and CLIs
   open                                            Open Clerk resources in your browser
+  security                                        Audit an instance against Clerk's security recommendations
   telemetry                                       Control CLI usage telemetry (status, disable, enable)
   unlink           [options]                      Unlink this project from its Clerk application
   update           [options]                      Update the Clerk CLI to the latest version

packages/cli-core/src/cli-program.ts

@@ -18,6 +18,7 @@ import { registerTelemetry } from "./commands/telemetry/index.ts";
 import { registerToggles } from "./commands/toggles/index.ts";
 import { registerApi } from "./commands/api/index.ts";
 import { registerDoctor } from "./commands/doctor/index.ts";
+import { registerSecurity } from "./commands/security/index.ts";
 import { registerMcp } from "./commands/mcp/index.ts";
 import { registerSwitchEnv } from "./commands/switch-env/index.ts";
 import { registerCompletion } from "./commands/completion/index.ts";
@@ -79,6 +80,7 @@ const registrants: CommandRegistrant[] = [
   registerToggles,
   registerApi,
   registerDoctor,
+  registerSecurity,
   registerMcp,
   registerSwitchEnv,
   registerCompletion,

packages/cli-core/src/commands/completion/__complete.ts

@@ -1,5 +1,6 @@
 import type { CommandUnknownOpts, Option } from "@commander-js/extra-typings";
 import { sources } from "../migrate/sources/registry.ts";
+import { CHECKS, findCheck } from "../security/catalog.ts";
 import { KNOWN_DASHBOARD_PATHS } from "../open/dashboard-paths.ts";
 
 const DIRECTIVE = {
@@ -60,6 +61,10 @@ const KNOWN_OPTION_VALUES: Record<string, Completion[]> = {
     { name: "canary", description: "Latest canary (pre-release) build" },
   ],
   "--source": SOURCE_COMPLETIONS,
+  "--factors": [
+    ...findCheck("mfa")!.decision!.options.map((o) => ({ name: o.value, description: o.label })),
+    { name: "authenticator,backup-code", description: "Authenticator app and backup codes" },
+  ],
   "--for": [
     { name: "orgs", description: "Organizations only" },
     { name: "users", description: "Users only" },
@@ -78,6 +83,7 @@ const KNOWN_POSITIONAL_COMPLETIONS: Record<string, Completion[]> = {
     name: path,
     description: "Dashboard subpath",
   })),
+  "security fix": CHECKS.map((check) => ({ name: check.id, description: check.title })),
 };
 
 /**
@@ -219,11 +225,14 @@ function completeArguments(
   consumedCount: number,
 ): CompletionResult {
   const registeredArgs = cmd.registeredArguments;
-  if (consumedCount >= registeredArgs.length) {
-    return EMPTY_NO_FILE;
-  }
-
-  const arg = registeredArgs[consumedCount];
+  const last = registeredArgs.at(-1);
+  const arg =
+    consumedCount < registeredArgs.length
+      ? registeredArgs[consumedCount]
+      : last?.variadic
+        ? last
+        : undefined;
+  if (!arg) return EMPTY_NO_FILE;
 
   // Prefer strict Commander choices when available.
   if (arg?.argChoices) {

packages/cli-core/src/commands/config/apply-patch.ts

@@ -24,6 +24,8 @@ export interface ApplyPatchOptions {
   warning?: string;
   /** Pre-fetched current config; skips the extra GET when caller already has it. */
   currentConfig?: Record<string, unknown>;
+  /** Receives the response body: the written document, or the projection under `--dry-run`. */
+  onWritten?: (body: Record<string, unknown>) => void;
 }
 
 /** Fetch + diff + confirm + PATCH, matching `clerk config patch` semantics. */
@@ -67,6 +69,7 @@ export async function applyConfigPatch(opts: ApplyPatchOptions): Promise<boolean
   );
 
   log.debug(`config: ${JSON.stringify(result.body)}`);
+  opts.onWritten?.(result.body);
   if (dryRun) {
     log.success("[dry-run] Validation passed — no changes applied");
   } else {

packages/cli-core/src/commands/deploy/providers.ts

@@ -5,6 +5,7 @@ import { clerkSubdomains } from "./copy.ts";
 import { log } from "../../lib/log.ts";
 import { wrap } from "../../lib/wrap.ts";
 import { openBrowser } from "../../lib/open.ts";
+import { OAUTH_KEY_PREFIX } from "../../lib/oauth-connections.ts";
 import type {
   ConfigSchemaProperty,
   IOSApplication,
@@ -134,8 +135,6 @@ type ProviderWithOverride = keyof typeof PROVIDER_OVERRIDES;
 
 const SYSTEM_FIELD_KEYS = new Set(["enabled", "authenticatable", "block_email_subaddresses"]);
 const DEFAULT_FIELD_ORDER = ["client_id", "client_secret"];
-export const OAUTH_KEY_PREFIX = "connection_oauth_";
-
 const SHARED_OAUTH_METADATA = new Map<string, (typeof OAUTH_PROVIDERS)[number]>(
   OAUTH_PROVIDERS.map((provider) => [provider.provider, provider]),
 );

packages/cli-core/src/commands/deploy/status.ts

@@ -30,7 +30,6 @@ import {
 } from "./copy.ts";
 import { mapDeployError } from "./errors.ts";
 import {
-  OAUTH_KEY_PREFIX,
   buildOAuthProviderDescriptors,
   hasProviderRequiredCredentials,
   inspectNativeAppleConfiguration,
@@ -41,6 +40,10 @@ import {
   type OAuthProvider,
   type OAuthProviderDescriptor,
 } from "./providers.ts";
+import {
+  discoverEnabledOAuthProviderSlugs,
+  OAUTH_KEY_PREFIX,
+} from "../../lib/oauth-connections.ts";
 import { pendingOAuthProviders, resolveActiveReportState } from "./report-state.ts";
 import type { DeployContext, DeployOperationState } from "./state.ts";
 import { recordDomainObservation, recordOAuthObservation } from "./telemetry.ts";
@@ -749,17 +752,6 @@ export async function loadProductionDomain(
   return domains.data.find((domain) => !domain.is_satellite) ?? domains.data[0];
 }
 
-export function discoverEnabledOAuthProviderSlugs(config: Record<string, unknown>): string[] {
-  const providers: string[] = [];
-  for (const [key, value] of Object.entries(config)) {
-    if (!key.startsWith(OAUTH_KEY_PREFIX)) continue;
-    if (!value || typeof value !== "object") continue;
-    if ((value as Record<string, unknown>).enabled !== true) continue;
-    providers.push(key.slice(OAUTH_KEY_PREFIX.length));
-  }
-  return providers;
-}
-
 export async function waitForDeployStatus(
   appId: string,
   domainIdOrName: string,