認証
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
ハッシュは同梱 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 呼び出しは無資格情報のバイパスを維持