tanstack-start-auth

TanStack Start + Better Auth

FMC アプリ（TILDA、Trassenscout の移行など）におけるライブラリの設定とStart 固有の連携に関するスキルです。

適用する場面

• betterAuth() / createAuthClient() の設定を作成または変更するとき
• /api/auth/*、tanstackStartCookies() プラグイン、OAuth サインインルートをマウントするとき
• beforeLoad ゲート、endpointAuth、サーバー関数または API ハンドラーでセッションを扱うとき
• パブリックと保護されたサーバー関数（public*.functions.ts の命名規則）
• 自動化エンドポイントで API キーとセッションによる二重認証を行うとき

リファレンス（必要に応じて参照）

トピック	ファイル
TanStack のルート、Cookie、セッションヘルパー、TILDA のパターン	references/auth.md
Trassenscout の認証リントのパターン	references/endpoint-auth-lint.md
betterAuth のオプション、DB、プラグイン、セッション、フック	references/better-auth-config.md

ライブドキュメント： better-auth.com/docs · llms.txt

関連スキル

• tanstack-router-conventions — validateSearch、検索パラメーターのシリアライズ、ローダー + Query
• tanstack-start-conventions — レイアウト、.server.ts / .functions.ts、境界、SSR
• playwright-skill — E2E の認証スタブ（TILDA）

必須ルール

1. セッションヘルパーには、常に現在のリクエストから取得した headers: Headers を渡します。
2. ルートの beforeLoad から DB／セッションを直接呼び出してはいけません。サーバー関数と getRequestHeaders() を使用します。
3. 公式の tanstackStartCookies() を最後のプラグインとして使用します。better-auth のバージョン変更後は、クライアントバンドルへの漏出がないことを確認します（auth.md）。
4. /api/auth/$ などのハンドラー専用 API ルートには、ssr: false を設定します（selective-ssr.md）。
5. API ルートでは、各ハンドラー内で認証を行います（ルートレベルの beforeLoad は使用しません）。
6. Cookie キャッシュを使用した管理者／ロールのチェックでは、getSession({ query: { disableCookieCache: true } }) を使用します。
7. API シークレットの比較には、タイミングセーフな等価性チェックを使用します。
8. 二層構造： beforeLoad はルートの UX 専用です。データ境界には endpointAuth／ガードを使用します。beforeLoad のみに依存してはいけません。
9. ルートのガードに認証ミドルウェアを使用してはいけません。レイアウトの beforeLoad を使用します。グローバル認証ミドルウェアは、パブリック RPC（public*.functions.ts、getSessionForRouteFn）を妨げ、FMC の認証ルートのパターンにも適合しません。

クイックパターン

// beforeLoad (via server fn)
await routeSessionFn({ data: location })

// API handler
const session = await endpointAuth.session(request.headers)

// Server function
const headers = getRequestHeaders()
await endpointAuth.admin(headers)

セットアップの概要

1. auth.server.ts で betterAuth() を設定します（Prisma／Drizzle アダプター、プラグイン）。
2. 対応するクライアントプラグインを使って createAuthClient() を設定します。
3. /api/auth/$ → auth.handler(request)（Cookie は tanstackStartCookies() プラグインを介して処理します）。
4. Headers を受け取る session.server.ts ヘルパーを用意します。
5. プラグインを変更した後は、CLI でマイグレーション／生成を実行します。詳細は better-auth-config.md を参照してください。