認証
ChatWalaʻau には補完的な 2 つの認証機構があります。統合 API キー（Bearer トークン） と、クラウドデプロイ向けの任意の Web サインイン（ユーザー名/パスワード）です。
統合 API キー
API_KEY は、外部 OpenAI API・すべての書き込み REST エンドポイント・**非ループバック
（LAN）**クライアントから到達した AG-UI チャットストリームを保護する単一の Bearer
トークンです。同一マシンのクライアント（127.0.0.1, ::1, localhost）は認証を
バイパスするため、APP_HOST=0.0.0.0 でもローカル開発はゼロ設定のままです。
API_KEY=sk-chatwalaau-your-secret-key-here
# APP_REQUIRE_AUTH_ON_LAN=true # 既定: キー無しの LAN はフェイルクローズ
書き込みエンドポイントと **AG-UI チャットストリーム（POST /ag-ui/）**の判定表:
| クライアントアドレス | APP_REQUIRE_AUTH_ON_LAN | API_KEY | 結果 |
|---|---|---|---|
| ループバック | 任意 | 任意 | 許可 |
| LAN | false | 任意 | 許可（オペレータのオプトアウト） |
| LAN | true | 空 | 503 |
| LAN | true | 設定済み | Bearer 必須 |
/v1/responses はクライアントアドレスに関わらず常に一致する Bearer キーを要求します。
APP_HOST が非ループバックで API_KEY 未設定の場合、AG-UI ストリームは他の書き込み
エンドポイントと同じく 503 / 401 を返すようになりました。API_KEY=... を追加するか、
APP_REQUIRE_AUTH_ON_LAN=false で LAN 公開を明示的に許可してください。
Web SPA 認証（任意）
ChatWalaʻau を、単一のオペレータがブラウザでサインインするプライベートなクラウド Web
アプリと してデプロイする場合に使います。API_KEY（CLI / SDK 用に残る）と共存し、
既定で無効です。AUTH_USERNAME を設定しなければ挙動は変わりません。
AUTH_USERNAME=admin
AUTH_PASSWORD_HASH=scrypt$N=16384,r=8,p=1$<base64-salt>$<base64-hash>
# AUTH_SESSION_TTL_SECONDS=86400 # 既定 24h、スライディング
# AUTH_COOKIE_SECURE=auto # auto / true / false
# AUTH_COOKIE_NAME=chatwalaau_session
# AUTH_SESSION_PERSIST=true # 再起動を跨いでセッションを維持（既定）
# AUTH_SESSION_STORE_PATH=.auth/session_tokens.json
ハッシュは同梱 CLI で生成します:
chatwalaau hash-password # 対話（2 回確認）
echo "$PASSWORD" | chatwalaau hash-password --stdin --quiet # スクリプト
AUTH_USERNAME を設定すると SPA は /login を描画し、サーバは定数時間で資格情報を
検証して不透明トークンを HttpOnly + SameSite=Strict Cookie で発行します。以降、
バックエンドはすべての書き込みエンドポイントと AG-UI ストリームで、Bearer API_KEY
または有効なセッション Cookie のいずれかを受け付けます。/v1/responses は
Bearer のみのままです。
- 追加の Python 依存なし（標準ライブラリの
hashlib.scrypt+secrets） - 単一ユーザー・単一プロセスモデル
- 非ループバックデプロイでは HTTPS を強く推奨
- ループバックの CLI 呼び出しは無資格情報のバイパスを維持
セッションは再起動を生き延びます
v0.104.0 以降、サインインはバックエンドの再起動を生き延びます。デプロイ、クラッシュ、
開発サーバの再起動のいずれでも、全ブラウザがログイン画面へ戻されることはありません。
サーバが AUTH_SESSION_STORE_PATH に保存するのはセッショントークンの SHA-256
ダイジェストのみであり、トークン本体ではありません。したがってこのファイルが漏洩しても
有効な Cookie を作ることはできず、暗号化も不要です。書き込みはアトミックで、POSIX では
0600、git 管理からも除外されます。
全セッションをサインアウトさせるには、運用に合う方法を選んでください。
| 操作 | 効果 |
|---|---|
AUTH_SESSION_STORE_PATH を削除 | 次回の再起動で全セッションが終了 |
AUTH_PASSWORD_HASH をローテーション | 次回の再起動で全セッションが即時終了 |
AUTH_SESSION_PERSIST=false | 従来の挙動（プロセスと共にセッションが消滅）に戻す |
プロセスの再起動だけでは、もはやユーザーはサインアウトされません。
セッションが失効したとき
セッションが失効した場合（TTL 切れ、他所でのログアウト、パスワードのローテーション）、
アプリは /login へ再読み込みしません。そのままのチャットの上にサインインダイアログ
を開くので、入力中のメッセージ、添付、モデル選択はすべて保持されます。サインインすれば
元の場所に戻ります。/login ページは初回読み込み時と明示的なサインアウト後に使われます。
同様に、送信時にサーバへ到達できなかった場合、メッセージは破棄されずに Retry ボタン付きで入力欄へ戻されます。