clerk-auth

Clerk Auth - 破壊的変更とエラー防止ガイド

パッケージバージョン: @clerk/[email protected], @clerk/[email protected], @clerk/[email protected], @clerk/[email protected] 破壊的変更: 2025年11月 - API バージョン 2025-11-10、2024年10月 - Next.js v6 の非同期 auth() 最終更新日: 2025-11-22

---

v6.35.x と API 2025-11-10 の新機能（2025年11月）

1. API バージョン 2025-11-10（2025年11月10日）- 破壊的変更 ⚠️

影響対象: Clerk Billing／Commerce API を使用するアプリケーション

重要な変更:

• エンドポイント URL: /commerce/ → /billing/（30 以上のエンドポイント）

  GET /v1/commerce/plans → GET /v1/billing/plans
  GET /v1/commerce/statements → GET /v1/billing/statements
  POST /v1/me/commerce/checkouts → POST /v1/me/billing/checkouts
  

• フィールドの用語: payment_source → payment_method

  // OLD (deprecated)
  { payment_source_id: "...", payment_source: {...} }
  
  // NEW (required)
  { payment_method_id: "...", payment_method: {...} }
  

• 削除されたフィールド: Plans のレスポンスに次のフィールドが含まれなくなりました。

  • amount、amount_formatted（代わりに fee.amount を使用）
  • currency、currency_symbol（代わりに fee オブジェクトを使用）
  • payer_type（代わりに for_payer_type を使用）
  • annual_monthly_amount、annual_amount

• 削除されたエンドポイント:

  • Invoices エンドポイント（代わりに statements を使用）
  • Products エンドポイント

• null の処理: 明示的なルールが適用されます。null は「存在しない」を意味し、省略は「存在を主張しない」を意味します。

移行: API バージョン 2025-11-10 のサポートが含まれる v6.35.0 以降に SDK を更新してください。

公式ガイド: https://clerk.com/docs/guides/development/upgrading/upgrade-guides/2025-11-10

2. Next.js v6 の非同期 auth()（2024年10月）- 破壊的変更 ⚠️

影響対象: auth() を使用するすべての Next.js Server Components

// ❌ OLD (v5 - synchronous)
const { userId } = auth()

// ✅ NEW (v6 - asynchronous)
const { userId } = await auth()

こちらにも影響します: auth.protect() は middleware で非同期になりました。

// ❌ OLD (v5)
auth.protect()

// ✅ NEW (v6)
await auth.protect()

互換性: Next.js 15、16 に対応しています。デフォルトで静的レンダリングが行われます。

3. カスタム OAuth の PKCE サポート（2025年11月12日）

カスタム OIDC プロバイダーとソーシャル接続で、クライアントシークレットを安全に保存できないネイティブ／モバイルアプリケーションのセキュリティを強化する PKCE（Proof Key for Code Exchange）がサポートされるようになりました。

ユースケース: シークレットを安全に保存できないモバイルアプリ、ネイティブアプリ、パブリッククライアント。

4. クライアントの信頼: クレデンシャルスタッフィング対策（2025年11月14日）

ユーザーが認識されていないデバイスからサインインすると、自動的に追加認証が行われます。

• 有効なパスワードを持ち、2FA を設定していないユーザーに対して有効になります
• 設定は不要です
• すべての Clerk プランに含まれます

仕組み: 新しいデバイスからのサインインを検出すると、Clerk は追加の検証（メールコード、バックアップコード）を自動的に求めます。

5. Next.js 16 のサポート（2025年11月）

@clerk/nextjs v6.35.2+ には、サインアウト時における Next.js 16 のキャッシュ無効化の改善が含まれています。

---

重要なパターンとエラー防止

Next.js v6: 非同期 auth() ヘルパー

パターン:

import { auth } from '@clerk/nextjs/server'

export default async function Page() {
  const { userId } = await auth()  // ← Must await

  if (!userId) {
    return <div>Unauthorized</div>
  }

  return <div>User ID: {userId}</div>
}

Cloudflare Workers: authorizedParties（CSRF 防止）

重要: CSRF 攻撃を防ぐため、必ず authorizedParties を設定してください。

import { verifyToken } from '@clerk/backend'

const { data, error } = await verifyToken(token, {
  secretKey: c.env.CLERK_SECRET_KEY,
  // REQUIRED: Prevent CSRF attacks
  authorizedParties: ['https://yourdomain.com'],
})

理由: authorizedParties がないと、攻撃者が他のドメインの有効なトークンを使用できます。

出典: https://clerk.com/docs/reference/backend/verify-token

---

JWT テンプレート - サイズ制限とショートコード

JWT のサイズ制限: カスタムクレームは 1.2KB ⚠️

問題: ブラウザーの Cookie は 4KB に制限されています。Clerk のデフォルトクレームが約 2.8KB を使用するため、カスタムクレームに使えるのは 1.2KB です。

⚠️ 開発時の注意: Vite の開発モードでカスタム JWT クレームをテストすると、「431 Request Header Fields Too Large」 エラーが発生する場合があります。これは、URL 内の Clerk のハンドシェイクトークンが Vite の 8KB 制限を超えることが原因です。解決策については、Issue #11 を参照してください。

解決策:

// ✅ GOOD: Minimal claims
{
  "user_id": "{{user.id}}",
  "email": "{{user.primary_email_address}}",
  "role": "{{user.public_metadata.role}}"
}

// ❌ BAD: Exceeds limit
{
  "bio": "{{user.public_metadata.bio}}",  // 6KB field
  "all_metadata": "{{user.public_metadata}}"  // Entire object
}

ベストプラクティス: 大きなデータはデータベースに保存し、JWT には識別子／ロールのみを含めてください。

利用可能なショートコードのリファレンス

カテゴリ	ショートコード	例
ユーザー ID と名前	{{user.id}}、{{user.first_name}}、{{user.last_name}}、{{user.full_name}}	"John Doe"
連絡先	{{user.primary_email_address}}、{{user.primary_phone_address}}	"[email protected]"
プロフィール	{{user.image_url}}、{{user.username}}、{{user.created_at}}	"https://..."
検証	{{user.email_verified}}、{{user.phone_number_verified}}	true
メタデータ	{{user.public_metadata}}、{{user.public_metadata.FIELD}}	{"role": "admin"}
組織	org_id、org_slug、org_role（sessionClaims 内）	"org:admin"

高度な機能:

• 文字列補間: "{{user.last_name}} {{user.first_name}}"
• 条件付きフォールバック: "{{user.public_metadata.role || 'user'}}"
• ネストされたメタデータ: "{{user.public_metadata.profile.interests}}"

公式ドキュメント: https://clerk.com/docs/guides/sessions/jwt-templates

---

Clerk を使ったテスト

テスト用認証情報（固定 OTP: 424242）

テスト用メールアドレス（メールは送信されません。OTP は固定です）:

[email protected]
[email protected]

テスト用電話番号（SMS は送信されません。OTP は固定です）:

+12015550100
+19735550133

固定 OTP コード: 424242（すべてのテスト用認証情報で使用できます）

セッショントークンの生成（有効期間 60 秒）

スクリプト（scripts/generate-session-token.js）:

# Generate token
CLERK_SECRET_KEY=sk_test_... node scripts/generate-session-token.js

# Create new test user
CLERK_SECRET_KEY=sk_test_... node scripts/generate-session-token.js --create-user

# Auto-refresh token every 50 seconds
CLERK_SECRET_KEY=sk_test_... node scripts/generate-session-token.js --refresh

手動の手順:

1. ユーザーを作成: POST /v1/users
2. セッションを作成: POST /v1/sessions
3. トークンを生成: POST /v1/sessions/{session_id}/tokens
4. ヘッダーで使用: Authorization: Bearer <token>

Playwright による E2E テスト

Testing Token の管理を自動化するには、@clerk/testing をインストールします。

npm install -D @clerk/testing

グローバルセットアップ（global.setup.ts）:

import { clerkSetup } from '@clerk/testing/playwright'
import { test as setup } from '@playwright/test'

setup('global setup', async ({}) => {
  await clerkSetup()
})

テストファイル（auth.spec.ts）:

import { setupClerkTestingToken } from '@clerk/testing/playwright'
import { test } from '@playwright/test'

test('sign up', async ({ page }) => {
  await setupClerkTestingToken({ page })

  await page.goto('/sign-up')
  await page.fill('input[name="emailAddress"]', '[email protected]')
  await page.fill('input[name="password"]', 'TestPassword123!')
  await page.click('button[type="submit"]')

  // Verify with fixed OTP
  await page.fill('input[name="code"]', '424242')
  await page.click('button[type="submit"]')

  await expect(page).toHaveURL('/dashboard')
})

公式ドキュメント: https://clerk.com/docs/guides/development/testing/overview

---

既知の問題の予防

このスキルでは、文書化された 11 件の問題を予防します。

問題 #1: Clerk Secret Key の不足

エラー: "Missing Clerk Secret Key or API Key" 出典: https://stackoverflow.com/questions/77620604 予防策: 必ず .env.local に設定するか、wrangler secret put で設定してください。

問題 #2: API Key から Secret Key への移行

エラー: "apiKey is deprecated, use secretKey" 出典: https://clerk.com/docs/upgrade-guides/core-2/backend 予防策: すべての呼び出しで apiKey を secretKey に置き換えてください。

問題 #3: JWKS キャッシュの競合状態

エラー: "No JWK available" 出典: https://github.com/clerk/javascript/blob/main/packages/backend/CHANGELOG.md 予防策: @clerk/[email protected] 以降を使用してください（修正済み）。

問題 #4: authorizedParties の不足（CSRF）

エラー: エラーは発生しませんが、CSRF の脆弱性があります 出典: https://clerk.com/docs/reference/backend/verify-token 予防策: 必ず authorizedParties: ['https://yourdomain.com'] を設定してください。

問題 #5: インポートパスの変更（Core 2）

エラー: "Cannot find module" 出典: https://clerk.com/docs/upgrade-guides/core-2/backend 予防策: Core 2 用にインポートパスを更新してください。

問題 #6: JWT サイズ制限の超過

エラー: トークンがサイズ制限を超えています 出典: https://clerk.com/docs/backend-requests/making/custom-session-token 予防策: カスタムクレームを 1.2KB 未満にしてください。

問題 #7: 非推奨の API バージョン v1

エラー: "API version v1 is deprecated" 出典: https://clerk.com/docs/upgrade-guides/core-2/backend 予防策: 最新の SDK バージョンを使用してください（API v2025-11-10）。

問題 #8: ClerkProvider JSX コンポーネントのエラー

エラー: "cannot be used as a JSX component" 出典: https://stackoverflow.com/questions/79265537 予防策: @clerk/[email protected]+ で React 19 との互換性を確保してください。

問題 #9: 非同期 auth() ヘルパーの誤用

エラー: "auth() is not a function" 出典: https://clerk.com/changelog/2024-10-22-clerk-nextjs-v6 予防策: 必ず await してください: const { userId } = await auth()

問題 #10：環境変数の設定ミス

エラー：「Publishable Key がありません」またはシークレットが漏えいする 予防策：正しいプレフィックス（NEXT_PUBLIC_、VITE_）を使用し、シークレットは絶対にコミットしないでください

問題 #11：431 Request Header Fields Too Large（Vite 開発モード）

エラー：サインイン時に「431 Request Header Fields Too Large」が発生する 発生元：カスタム JWT クレームをテストする際、Vite 開発モードでよく発生します 原因：URL 内の Clerk の __clerk_handshake トークンが Vite の 8KB ヘッダー制限を超えます 予防策：

package.json に追加します：

{
  "scripts": {
    "dev": "NODE_OPTIONS='--max-http-header-size=32768' vite"
  }
}

一時的な回避策：ブラウザーのキャッシュをクリアし、サインアウトしてから再度サインインします

理由：Clerk の開発用トークンは本番環境より大きく、カスタム JWT クレームによってハンドシェイクトークンのサイズが増加します

注：これは問題 #6（セッショントークンのサイズ）とは異なります。問題 #6 は Cookie（1.2KB）に関するもので、こちらは開発モードの URL パラメーター（8KB → 32KB）に関するものです。

---

公式ドキュメント

• Clerk ドキュメント：https://clerk.com/docs
• Next.js ガイド：https://clerk.com/docs/references/nextjs/overview
• React ガイド：https://clerk.com/docs/references/react/overview
• バックエンド SDK：https://clerk.com/docs/reference/backend/overview
• JWT テンプレート：https://clerk.com/docs/guides/sessions/jwt-templates
• API バージョン 2025-11-10 へのアップグレード：https://clerk.com/docs/guides/development/upgrading/upgrade-guides/2025-11-10
• テストガイド：https://clerk.com/docs/guides/development/testing/overview
• Context7 ライブラリ ID：/clerk/clerk-docs

---

パッケージのバージョン

最新（2025年11月22日）：

{
  "dependencies": {
    "@clerk/nextjs": "^6.35.4",
    "@clerk/clerk-react": "^5.56.2",
    "@clerk/backend": "^2.23.2",
    "@clerk/testing": "^1.13.18"
  }
}

---

トークン効率：

• スキルなし：約5,200トークン（セットアップチュートリアル、JWT テンプレート、テスト環境のセットアップ）
• スキルあり：約2,500トークン（破壊的変更＋重要なパターン＋エラーの予防）
• 削減率：約52%（約2,700トークン）

予防できるエラー：解決策を明記した11件の既知の問題 主な価値：API 2025-11-10 の破壊的変更、Next.js v6 の非同期 auth()、カスタム OAuth 用 PKCE、クレデンシャルスタッフィング対策、JWT サイズ制限、431 ヘッダーエラーの回避策

---

最終確認日：2025-11-22 | スキルのバージョン：2.0.0 | 変更内容：API バージョン 2025-11-10 の破壊的変更（請求エンドポイント）、PKCE サポート、Client Trust 対策、Next.js 16 サポートを追加。チュートリアル（約480行）を削除。SDK のバージョンを更新。破壊的変更＋エラーの予防＋重要なパターンに重点を置きました。