feat(cli-auth): add @clerk/cli-auth package

.changeset/loud-callbacks-listen.md

@@ -0,0 +1,27 @@
+---
+'@clerk/cli-auth': minor
+---
+
+Add `@clerk/cli-auth`: reusable OAuth 2.0 + PKCE localhost-callback flow for adding Clerk authentication to Node.js CLIs.
+
+The default export (`@clerk/cli-auth`) ships the CLI-side runtime: browser-based sign-in via a one-shot localhost callback server, token storage (keychain with file fallback, file, or memory), token refresh, revocation, `/oauth/userinfo` lookup, multi-credential resolution via `resolveToken()` (returns `{ token, source }` where `source` is `'arg' | 'env' | 'oauth'`), optional `identityEndpoint`-backed verification, and tunable timeouts (`loginTimeoutMs`, `requestTimeoutMs`).
+
+The new `@clerk/cli-auth/server` subpath ships a backend route handler that consumers drop into any framework using Web `Request`/`Response` (Next.js App Router, Hono, Cloudflare Workers, Bun, Deno):
+
+```ts
+// lib/clerk-cli.ts
+import { cliAuth } from '@clerk/cli-auth/server';
+import { clerkClient } from '@clerk/nextjs/server';
+
+export const auth = cliAuth({ client: clerkClient });
+
+// app/api/cli/identity/route.ts
+import { handle } from '@clerk/cli-auth/server';
+import { auth } from '@/lib/clerk-cli';
+
+export const GET = handle({ auth, accepts: ['api_key', 'oauth_token'] });
+```
+
+`cliAuth({ client | clientConfig })` binds a `@clerk/backend` client once and returns an instance exposing `verifyToken(token)`, `verifyTokenFromRequest(request)`, `resolveAuthInfo(ctx)`, and `getClerk()`. The standalone `handle({ auth, accepts, verifyToken?, resolveAuthInfo? })` produces a route handler that auto-detects token type, gates against `accepts`, verifies via `@clerk/backend`'s `verifyMachineAuthToken`, and returns an `Identity` JSON payload. Override the verification or resolution steps per-route by passing the corresponding callbacks.
+
+`accepts` recognizes `'api_key'` (covers user, org, and machine subjects), `'oauth_token'` (opaque `oat_*` or RFC 9068 `at+jwt` JWTs), or `'any'`. The narrowed `TokenKind` excludes Clerk session tokens and M2M tokens — neither is a CLI credential.

.github/labeler.yml

@@ -12,6 +12,10 @@ chrome-extension:
   - changed-files:
       - any-glob-to-any-file: packages/chrome-extension/**
 
+cli-auth:
+  - changed-files:
+      - any-glob-to-any-file: packages/cli-auth/**
+
 clerk-js:
   - changed-files:
       - any-glob-to-any-file: packages/clerk-js/**

packages/cli-auth/.gitignore

@@ -0,0 +1,8 @@
+*.log
+.DS_Store
+.idea
+node_modules
+dist
+coverage
+.env
+.env.local

packages/cli-auth/.npmignore

@@ -0,0 +1,2 @@
+*
+!/dist/**/*

packages/cli-auth/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Clerk, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.