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

.changeset/security-recommendations.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk security`, a security audit for a Clerk instance. `clerk security audit` grades the instance against 19 recommendations (bot protection, breached-password detection, brute-force lockout, device trust, MFA, session limits, sign-up restrictions, and more), prints a report grouped by severity, and exits 1 when a critical recommendation is unmet (tunable with `--fail-on`). In agent mode or with `--json` every finding carries the exact `clerk config patch` payload that closes it. `clerk security fix <ids...>` applies the patches as one config patch with a diff, a confirmation, and server-side `--dry-run`, then reports the new grade and the remaining gaps. Bare `clerk security fix` opens a checklist; `--all` applies every critical and recommended gap, with `--good-to-have` opting into the rest. Checks that need a product decision, such as which second factors to offer, ask interactively or take `--factors` / `--strategy` from agents. `clerk security checks` lists the catalog offline.

README.md

@@ -87,6 +87,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";
@@ -77,6 +78,7 @@ const registrants: CommandRegistrant[] = [
   registerToggles,
   registerApi,
   registerDoctor,
+  registerSecurity,
   registerMcp,
   registerSwitchEnv,
   registerCompletion,

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

@@ -1,4 +1,5 @@
 import type { CommandUnknownOpts, Option } from "@commander-js/extra-typings";
+import { CHECKS } from "../security/catalog.ts";
 import { KNOWN_DASHBOARD_PATHS } from "../open/dashboard-paths.ts";
 
 const DIRECTIVE = {
@@ -52,6 +53,12 @@ const KNOWN_OPTION_VALUES: Record<string, Completion[]> = {
     { name: "latest", description: "Latest stable release" },
     { name: "canary", description: "Latest canary (pre-release) build" },
   ],
+  "--factors": [
+    { name: "authenticator", description: "Authenticator app (TOTP)" },
+    { name: "backup-code", description: "Backup codes" },
+    { name: "sms", description: "SMS code" },
+    { name: "authenticator,backup-code", description: "Authenticator app and backup codes" },
+  ],
   "--for": [
     { name: "orgs", description: "Organizations only" },
     { name: "users", description: "Users only" },
@@ -70,6 +77,7 @@ const KNOWN_POSITIONAL_COMPLETIONS: Record<string, Completion[]> = {
     name: path,
     description: "Dashboard subpath",
   })),
+  "security fix": CHECKS.map((check) => ({ name: check.id, description: check.title })),
 };
 
 /**
@@ -211,11 +219,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 {