認証と認可

データベースを基盤とするシステムでは早い段階で「ログインはどこに置くのか」という問いが出ます。Kozou の答えは意図的なもので、2 つの軸にきれいに分かれます。

2 つの問い、2 つの軸

セキュリティには異なる 2 つの問いがあり、混同すると混乱します。

テキストは信頼できるか？ — COMMENT の信頼境界。PostgreSQL を信頼できる源とするで扱います。これはプロンプトインジェクションの話で、Kozou が AI エージェントに転送する COMMENT テキストは、信頼された主体が書いたものとして扱われます。
誰がデータを読み書きしてよいか？ — アクセス制御。本ページはこちらの軸を扱います。

本ページは 2 つめの問いに答えます。要点はこうです。Kozou は resource server / 施行層であり、identity provider ではありません。

Kozou が担うこと: resource server / 施行層

auth を有効にすると、自前の REST バックエンド (@kozou/api) は、token を持つ各リクエストについて署名付き JWT を検証し（HS256 共有秘密鍵 / RS256 公開鍵 / プロバイダのリモート JWKS エンドポイント）、そのリクエストをトランザクション内で次のように実行します。

SET LOCAL ROLE <claim の role>;
-- request.jwt.claims も公開されるので、policy は claims を読める

ここから先は、あなた自身の PostgreSQL 行レベルセキュリティ (RLS) ポリシーが、そのリクエストの読み書き可否を決めます。 Kozou は role を切り替えて claims を公開するだけで、policy は書きません。施行はデータベース内に存在するため、経路非依存です — それらのポリシーの対象となる role で接続する限り、Kozou 経由でも、psql 経由でも、他のどの client 経由でも、同じ RLS が適用されます。

これはアプリケーションが既に必要とするロールにそのまま対応します。「管理者」「編集者」「投稿者」「閲覧者」は PostgreSQL のロール + RLS ポリシーであり、Kozou は検証済み token が示すロールの下で各リクエストを実行します。token のないリクエストは 401 で拒否されますが、匿名ロールを設定した場合は、空の claims でそのロールの下で実行され、匿名の呼び出し元に何を見せるかをあなたの policy が決めます。

Kozou が担わないこと: identity provider

Kozou は identity を提供しません。以下は範囲外で、別の場所から来ることを前提とします。

ユーザー登録・セルフサービスのサインアップ、
ログイン・セッション・パスワードの保管/リセット、
OAuth・ソーシャルログイン、
JWT そのものの発行・リフレッシュ。

FastAPI Users 型の認証・ユーザー管理ライブラリは Kozou の非ゴールです。Kozou は token を消費しますが、発行はしません（kozou dev で同梱 Admin UI が使う内部サービストークンを除く）。

推奨構成

role claim 付きの JWT を発行する identity provider を用意し、Kozou をそこに向けます。

Supabase Auth — 推奨。 PostgreSQL-native で、role claim 付きの JWT を発行し、RLS を前提に設計されています — Kozou の施行モデルと完全に整合します。
Auth0 / Clerk — プロバイダのリモート JWKS エンドポイント (jwt.jwksUri) で検証します。鍵は kid で選択され、キャッシュされ、ローテーションで更新されます。
自前の最小 issuer — Kozou が検証する秘密鍵で role claim 付き JWT を mint する小さなサービスでも構いません。
企業向け OIDC プロバイダ（Entra ID / Okta / Google Workspace） — 社内・業務利用では、同じ JWKS 経路で社内 ID プロバイダに Kozou を向けます。Entra ID・Okta・Google でのシングルサインオンを参照。

これを配線する auth ブロックは kozou.config.yaml に、リクエストレベルの挙動は REST API ガイドに記載しています。

なぜこの境界なのか

Kozou は、あなたのスキーマからサーフェス（Admin UI・REST API・MCP context）へのコンパイラです。identity はその核に含まれない横断的関心事であり、かつシステム中で最も事故コスト・保守コストが高い面です — 認証情報の保管、パスワードリセット、アカウント乗っ取り、MFA、OAuth。これを hardened なプロバイダに委譲する方が良いトレードオフです。これはエコシステムが既に引いている境界でもあります — PostgREST はログインを自前実装せず identity を GoTrue / Supabase Auth に委譲します。Kozou も同じ線を引くことで focus を保ち、あなたの認証情報をそれを守るために作られたシステムに置きます。

Kozou が代わりに投資する先

認可のうち Kozou らしい部分は、ログイン画面ではなくモデルです。ロールと RLS ポリシーはスキーマに関する事実であり、Kozou はスキーマコンパイラです。したがって Kozou が投資する方向は、ロール + RLS の認可モデルをスキーマからコンパイルして surface すること — AI エージェントに示す @policy advisory タグ、生成ドキュメント、MCP context を通じて — であり、ログイン機能を作ることではありません。

次はどこへ

PostgreSQL を信頼できる源とする — もう一方のセキュリティ軸、COMMENT の信頼境界。
kozou.config.yaml — auth 設定ブロック。
REST API ガイド — リクエストレベルのセキュリティと JWT + RLS のフロー。