メインコンテンツまでスキップ

認証とアクセス権

認証は「誰が操作しているか」、認可は「その人がこのデータを操作してよいか」の確認です。ログインできることと、他の人の動画を読めることは別です。

入口によって認証方法が違う​

入口使う仕組み主な用途
ブラウザBetter AuthのCookieセッションログイン、プロフィール、通常のtRPC API
MCPクライアントAPIキーまたはOAuth外部ツールから動画・講座を操作する
公開共有リンク共有トークンと講座の公開状態などを確認共有された講座を利用する

MCPは、AIアシスタントなどの外部クライアントがツールを呼び出すためのプロトコルです。接続先は /api/mcp です。

ブラウザでログインするとき​

  1. ログイン画面が /api/auth/* のBetter Authへ情報を送ります。
  2. 認証が成功すると、セッションを表すCookieが設定されます。
  3. 以後のAPI呼び出しにもCookieを送り、API側で利用者を確認します。

React側のログイン判定は useSession、プロフィールの取得は account.me を使います。通常のブラウザAPI用に独自のアクセストークン更新処理を追加する必要はありません。

セッションはCookieキャッシュを使わずDBで確認します。無効化された利用者は新しいセッションを作れず、停止中の利用者は既存セッションでもBetter Authの管理者APIやAPIキー管理APIを利用できません。ログアウトは引き続き可能です。

アカウント停止・再開・管理者ロール変更は、公式Adminプラグインの banUser / unbanUser / setRole を使用します。権限は一般ユーザー(user)と管理者(admin)の2種類です。認証・認可では公式の banned と role を参照し、APIでは管理者権限を is_admin として返します。旧 is_staff / is_superuser 列は 0028 で削除し、残る旧 is_active 列も認証・認可には使いません。停止時のブラウザセッション失効は公式へ任せ、APIキーやOAuthの利用・発行にも停止状態を適用します。OAuthの同意やオフライン連携は削除せず、停止解除後は有効なAPIキー・更新トークンを再利用できます。連携そのものを削除するときは、明示的に連携解除を行います。

認証プラグインの管理APIにも2種類のロール制約を適用します。set-role / update-user を直接呼んでも、自分の管理者権限は解除できません。

実装の境界​

Better Authの公式オプション、プラグイン、サーバー・クライアントAPIを優先します。パスワードのハッシュ化、セッションCookie、メール確認、Googleトークンの検証、OAuthプロトコルの検証、プロバイダートークンの暗号化はBetter Authに任せます。型もBetter Authから推論されたものを使います。障害によるセッション取得の失敗はログアウトとして扱わず、サーバー側の認証拒否だけをアプリの通常の未認証応答へ変換します。

要件Better Authの実装
パスワード・ユーザー名ログイン、Googleログイン、メール確認・変更、復旧、Cookieコアのオプション、Googleプロバイダー、username プラグイン
管理者ロールとアカウント停止admin プラグインの setRole、banUser、unbanUser、adminUpdateUser API
APIキーの作成、保存、権限、検証、失効@better-auth/api-key の設定と permissions、公式の verifyApiKey とアクセス制御ヘルパー
OAuth/OIDC、PKCE、更新トークンのローテーション、再利用検知@better-auth/oauth-provider と jwt
MCPリソースの検出とBearer/DPoPチャレンジ公式のOAuth Resource Clientと createResourceServerChallenge
VideoQのアカウント状態確認と、連携解除後の更新停止補助プラグイン videoq-auth-security
検証済みAPIキーまたはOAuthトークンによるMCPアクセスサーバー専用プラグイン videoq-resource-access のAPI

補助プラグインが追加するのは、標準プラグインにないアプリ固有のポリシーだけです。リソースの検証は auth.api.verifyVideoqApiKey と auth.api.verifyVideoqOAuth でだけ行い、どちらも標準の検証にVideoQのアカウント・アクセスのポリシーを加えます。Honoは認証方式の選択と、結果のアプリ権限・HTTP応答への対応付けだけを担当します。

CloudflareのWorkerは同じゾーンの自分のRouteを取得できないため、リソースプラグインはBetter Authの公開JWT・DPoPヘルパーとJWTプラグインのプロセス内JWKSエンドポイントを組み合わせます。DPoPの再利用防止には、Worker間で共有されるBetter Auth標準のDBバックエンド createDpopReplayStore を使います。設定済みのロガーは、プロバイダーの応答、トークンを含むURL、SQLの詳細をライブラリログから除外します。

Better Authの更新時は、実際のrouteを使う回帰テストを維持してください。同じ動作を提供する機能がライブラリに追加されたら回避策を削除し、独自の認証ロジックは実証済みの不足またはVideoQ固有の要件がある場合だけ追加します。

仕様を見直した判断​

標準機能と公式プラグインを優先し、次の範囲に絞ります。

仕様判断と理由
連携解除や同意変更で発行済みJWTを即時失効させる廃止。公式の短い有効期限による運用に合わせ、新規発行分は最大5分にする
連携を解除している間の更新を停止する維持。同意削除だけでは更新トークンが残るため、トークン削除と現在の同意確認を追加する
再連携後も同意の世代を厳密に区別する廃止。現在の同意・スコープを確認し、コードの期限・単回利用・PKCE・更新処理は公式へ任せる
停止ユーザーの利用拒否維持。公式のAPIキー・JWT検証だけでは所有者の停止状態が適用されないため
利用停止時にOAuth連携をすべて削除する廃止。公式のセッション失効と停止中の利用拒否に揃え、連携解除時にトークンを削除する
復旧やメール・パスワード変更時に他の再設定リンクを一括無効化する廃止。公式のハッシュ保存、15分期限、単回利用、復旧時のセッション失効を使用する
Worker内でのJWKS取得接続用の小さな拡張を維持。現在の公式検証APIはHTTP取得を必要とするため

トークン発行時に現在の同意とスコープを照合します。公式の customTokenResponseFields コールバックで、PKCE検証後・トークン保存前の認可リクエストを確認します。更新時は公開フックと公式のハッシュ関数で保存済みトークンに対応する同意を確認します。認可コードの内部JSONの解析・書き換え、独自の同意ID埋め込みは行いません。JWTの独自クレームや、MCPで毎回同意・クライアントを照会する処理もありません。

利用者が同じアプリに明示的に再同意すると、期限内・未使用の認可コードは現在許可された範囲で交換できる場合があります。削除済みの更新トークンは復活しません。解除と同時に進んでいた更新でトークンが残った場合も、次回の使用時に現在の同意を確認します。解除中のコード交換は拒否し、そのコードは公式処理で消費されるため再連携後にも再利用できません。

パスワード再設定は、コアの verification.storeIdentifier に reset-password: 用の "hashed" を設定し、有効期限を15分、revokeSessionsOnPasswordReset を有効にします。単回利用も公式が原子的に処理します。別々に発行したリンクは、メールやパスワードの変更後もそれぞれの使用・期限切れまで有効です。復旧時のコールバックはアプリの旧 passwordResetRequired フラグを更新するだけです。

APIキーの権限は公式API Keyプラグインの permissions で管理します。default 設定は読み取り、read-write 設定は読み書きを許可し、ブラウザは設定IDを選択します。権限自体の設定はサーバーが行います。旧メタデータの accessLevel / access_level による独自判定は使用しません。

MCPの公開メタデータと認証チャレンジは公式OAuth Resource Clientと createResourceServerChallenge を使用します。公式MCPプラグインは1.7.5も確認しましたが、リクエスト検証はHTTPのJWKS URLを受け取り、Worker内の鍵取得関数は指定できません。そのため、同じWorker内でJWKSを取得する接続処理は拡張として残します。JWT・DPoPの検証と再利用検知はBetter Authの公開APIを利用します。VideoQの各ツールに必要なスコープの対応付けはアプリ固有の設定として残し、リクエストの判別はMCP SDKの公式スキーマ、権限不足の応答はBetter Authの公式機能に任せます。

既存環境の移行​

既存環境への移行には 0021_better_auth_permissions_and_account_state.sql の適用が必要です。旧アプリによる認証・管理情報の更新を一時停止し、通常のDrizzleマイグレーションを実行してから新コードを反映してください。旧APIキーの権限、利用停止状態、管理者フラグを公式フィールドへ移します。APIキーのハッシュは変更せず、再発行も不要です。

旧 is_staff / is_superuser 列を削除する 0028_remove_legacy_user_roles は、既存の role を保持します。本番ではこの整理が完了しています。古い環境では、これらの列を読むAPIから切り替えてから 0028 を適用してください。

再設定リンクの保存方式を変更する前に 0022_standard_password_reset_identifiers.sql も適用します。旧形式の接頭辞付き16進SHA-256を公式のbase64url形式に変換し、発行済みリンクと元の有効期限を維持します。他用途の確認情報や旧平文リンクは変更しません。移行からコード反映まで認証情報の書き込みを止め、旧形式のレコードが再作成されることを防いでください。15分の期限は新規リンクに適用されます。

tRPCでの確認​

procedure入口で確認すること
publicProcedureログインを一律には要求しない。共有トークンなどの確認は処理ごとに行う
protectedProcedureブラウザのログインセッション
adminProcedure管理者権限

その後、サービスやDB問い合わせでも所有者・講座へのアクセス範囲を確認します。API変更時は「自分のデータでは成功し、権限のない他人のデータでは失敗する」を確認します。

定義は packages/trpc/src/init.ts、リクエストとの接続は trpc/context.tsにあります。

講座の共有と招待​

所有者・招待参加者・共有リンク利用者の権限表、AI回答枠の負担者、履歴の公開範囲、取り消し手順は、共有・招待の権限とチャット履歴を参照してください。

MCPでの確認​

APIキーは設定画面で管理します。OAuthでは利用者がクライアントへのアクセスを許可し、videoq.read / videoq.write などの範囲で操作します。ブラウザのセッションとMCPのトークンを同じものとして扱わないでください。

接続時の認証応答はスコープを読み取りだけに絞らず、公開メタデータから読み取り・書き込みの両方を要求できるようにします。読み取り専用のOAuthトークンで書き込みツールを呼ぶと、Better Authの公式機能でHTTP 403と insufficient_scope、必要な両スコープを返し、クライアントから再同意を求められるようにします。既存トークンの権限は自動で増えません。動的登録で videoq.read だけを要求しても、Better Authはサーバー設定で許可した登録上の権限を保持するため、同じクライアントの再認可・追加同意で書き込みを許可できます。クライアントの再登録は不要です。追加認可の要求に対応しないクライアントでは、認可をやり直して両スコープを要求してください。

連携解除では、その利用者と対象アプリの同意情報・アクセス/リフレッシュトークンのレコードを一つのトランザクションで削除します。以後の発行には現在の同意とスコープの一致が必要です。再連携をまたぐ独自の世代管理は行いません。

発行済みJWTは有効期限まで利用でき、新規発行分は最大5分です。連携解除、同意スコープの変更、クライアント停止でMCPのJWTを即時失効させる独自処理は使用しません。利用停止中・削除済みのユーザーは即時拒否します。停止解除後は有効な連携を再利用できますが、失効済みのブラウザセッションは復活しません。APIキーの失効と保存済み不透明トークンの削除は即時に反映します。

OAuthで対応する認可方式は、認可コードの交換とリフレッシュです。resource を省略する正常なOAuth/OIDC連携も利用できます。UserInfoと認証済みクライアントからの照会では、公式のトークン・セッション検証にユーザーの停止確認だけを追加します。削除済み不透明トークン・更新トークンは無効、JWTは原則として期限まで有効です。公式OAuth Providerの失効モデルに合わせた動作です。

世代管理の削除によるOAuthの再認可・DB移行は不要で、保存済みの referenceId はアプリの権限判断に使用しません。既存JWTは元の期限まで有効で、従来のリソース設定では最大15分、新しい5分制限は発行時から適用されます。ブラウザセッションとAPIキーの形式は変わりません。前述の公式権限・アカウント状態・再設定リンク保存形式への移行が未適用の場合、そのマイグレーションは別途必要です。

設定名で迷ったら​

  • BETTER_AUTH_SECRET: Better Auth用の秘密鍵。ホスト実行・本番の設定で使用。
  • AUTH_JWT_SECRET: Compose起動スクリプトが転送する互換設定。現在のブラウザ認証方式を表す名前ではない。
  • USER_SECRET_ENCRYPTION_KEY: 利用者が保存した外部APIキーを暗号化・復号する鍵。セッションの秘密鍵とは用途が異なる。

次に読む: APIを変更する。通信の順番はシーケンス図でも確認できます。