カテゴリー: Fess

Fess 15.7.0をリリースしました。今回は、ヘッドレス用途やSPA（シングルページアプリケーション）フロントエンドを意識した新しい/api/v2 REST APIと、HTML/CSS/JavaScriptだけで検索画面を作れる静的テーマの仕組みが目玉になっています。マイルストーンを見てもらうと分かりますが、フロントエンドとAPIまわりを大きく作り直した、ボリュームのあるリリースになりました。

まず一番大きいのが、/api/v2に統一したREST APIです。これまで機能ごとにバラバラだったREST managerを、一貫したJSONエンベロープ（status、schema、data / error）にまとめました。検索やスクロール（NDJSON）、関連クエリ・関連コンテンツ、ドキュメントキャッシュ、お気に入り、クリックログ、認証（ログイン / ログアウト / me / パスワード変更）、CSRFトークン、ログインのレート制限、UI設定、そしてチャット（POSTおよびSSEストリーミング）まで、ひととおりカバーしています。OpenAPIの定義も同梱していて、入力値の上限チェック、状態を変更するリクエストへのCSRF必須化、IP単位・ユーザー単位のレート制限といったセキュリティ面の強化も合わせて入れています。

このAPI刷新にともなって、従来のv1 JSON検索API・チャットAPIは削除されました。もし既存のv1検索APIに依存している場合は、新しく用意したfess-webapp-v1-apiプラグインをインストールすると、これまでどおりの検索APIを使えるようになります。アップグレード時はこの点に注意してください。

次に、静的テーマ（Static Theme System）の仕組みを追加しました。検索画面を、JSPやActionを経由せずにWeb層から直接配信できる、自己完結したHTML/CSS/JavaScriptのバンドルとして提供できるようになっています。テーマはtheme.ymlのマニフェストでバリデーションされ、事前圧縮したアセットやキャッシュヘッダーにも対応します。ZIPアップロードでインストールでき、パストラバーサルやzip-bomb、サイズ上限といったセキュリティガードもしっかり入れてあります。管理画面には新しく「Admin → Theme」を追加して、アップロード・有効化・デフォルト設定・削除がそこから行えるようにしました。

その静的テーマを実際に動かすリファレンス実装として、Bootstrap 5ベースのテーマも同梱しています。素のES2022モジュールで作られていて、ホーム、ファセット付きの検索、詳細検索、キャッシュ表示、AIチャット、プロフィール、ヘルプといった既存の検索UIを、16言語で再現しています。そのまま使ってもいいですし、独自の検索フロントエンドを作るときの出発点としても使えるようにしています。

検索エンジン側では、OpenSearch 3.7に対応しました。バンドルしているkopfプラグインも15.7.0に合わせて更新しています。

セキュリティ周りもまとめて強化しています。状態を変更するv2リクエストにはCSRFを無条件で必須化し、ログインのスロットリングは（クライアントIP、ユーザー名）の単位に、匿名チャットのスロットリングはクライアントIP単位にスコープを切るようにしました。認証情報付きのCORSは許可リストに載せたオリジンだけに制限し、関連コンテンツのプレースホルダーでは検索クエリをエンコードして反射型XSSを防いでいます。セッションCookieにSecure属性を付けるためのsession.cookie.secureオプションも追加しました。このほか、匿名のヘルスレスポンスからcluster_nameを出さないようにしたり、v2レスポンスをデフォルトでCache-Control: no-storeにしたり、クリックのquery_idの妥当性を検証してランクの値を範囲内に収めたりと、細かいところを地道に固めています。

AI Search Mode（RAGチャット）も改善しました。大きなドキュメントから回答を生成するときに、ハイライトされたパッセージを使うようにしています。スマートサマリーは「Minimal Trail」として作り直し、フェーズごとに履歴を持つ形に見直しました。LLMのリトライ・待機・フォールバック・警告といった状態や、検索ヒット件数をブラウザに通知できるようにし、RAGのインテント処理では途中で切れたLLMレスポンスをフォールバックとして扱うようにしています。

クロール・インデックス周りでは、失敗URLとして扱うステータスコードのデフォルトにHTTP 403と410を追加しました。あわせてFessCrawlerThreadのホットパスを引き締め、API・クローラー・LLMのコード全体で正規表現パターンを事前コンパイルするようにして、処理を軽くしています。

そのほか、不具合修正として、デフォルトのGoogle Cloud Storageエンドポイントを使ったときにストレージ機能が正しく有効化されるよう直しています。

今回もコード修正からリリースノート作成、多言語ドキュメントの更新まで、Claude Codeにかなり助けてもらいました。/api/v2への統一と静的テーマの仕組みで、フロントエンドの自由度がぐっと上がっているので、ぜひ新しいFessを使ってみてください。

Fessの検索画面は、これまでJSPベースで提供してきました。デザインを大きく変えようとするとJSPやアクションに手を入れる必要があり、フロントエンドだけで完結させるのが難しい構成でした。

そこでFess 15.7で、統一されたWeb API /api/v2 と、HTML/CSS/JSだけで検索画面を構築できる静的テーマ機能を追加しました。これにより、Fessをバックエンドとして扱い、検索画面をシングルページアプリケーション（SPA）として自由に作れるようになります。

API v2 について

/api/v2 は、これまで機能ごとに分かれていたREST APIを単一のディスパッチャに統合したものです。検索・サジェスト・ラベル・お気に入り・クリックログ・認証・RAGチャットなど、検索画面を作るのに必要なエンドポイントがひと通り揃っています。

統一されたレスポンス形式

すべてのレスポンスは以下のように response でラップされた形で返ってきます。

{
  "response": {
    "status": 0,
    "...": "..."
  }
}

エラー時は以下のようになります。

{
  "response": {
    "status": 1,
    "error": {
      "code": "invalid_request",
      "message": "..."
    }
  }
}

status は 0（成功）、1（クライアントエラー）、9（システムエラー）の3種類です。error.code は invalid_request auth_required forbidden not_found rate_limited などの安定したコードになっており、クライアント側はメッセージ文字列ではなくこのコードで分岐・ローカライズします。JSONのキーはリクエスト・レスポンスともにすべてスネークケースで統一しています。

主なエンドポイント

代表的なものを挙げると以下の通りです。

メソッド + パス	用途
GET /api/v2/search	ドキュメント検索
GET /api/v2/suggest-words	サジェスト
GET /api/v2/labels	ラベル一覧
GET /api/v2/popular-words	人気の検索ワード
GET /api/v2/ui/config	UI初期化用の設定とCSRFトークン
GET /api/v2/auth/me	ログイン中のユーザー情報
POST /api/v2/auth/login	ログイン
POST /api/v2/click	クリックログの記録
POST /api/v2/chat/stream	RAGチャット（SSEストリーミング）
GET /api/v2/documents/all	スクロール検索（NDJSON）
GET /api/v2/health	クラスタのヘルスチェック

検索の例は以下のような感じです。

$ curl "http://localhost:8080/api/v2/search?q=fess&num=20"

GET /api/v2/search は q（クエリ）、start / num（ページング）、sort、lang、facet.field などのパラメータを受け取り、data（ドキュメント配列）、record_count、page_count、facet_field、related_query などをまとめて返します。

UI初期化とCSRF

SPAはまず GET /api/v2/ui/config を匿名で呼び出します。ここでサイト名・機能フラグ・ソートやページサイズの選択肢・テーマ情報、そしてCSRFトークンを取得します。

状態を変更するPOST/PUT/DELETEには X-Fess-CSRF-Token ヘッダーが必須です（/auth/login のみ例外）。トークンはログイン・ログアウト・パスワード変更のたびにローテーションされます。CSRF検証は認証より前に走るため、トークンなしの更新系リクエストは401ではなく403になります。

静的テーマ機能

検索画面は「テーマ」としてファイルシステムから直接配信されます。JSPやアクションを経由しないため、ブラウザのアドレスバーのURLもそのまま保持されます。

テーマは theme.yml というマニフェストを持ちます。

apiVersion: fess.codelibs.org/v1
kind: StaticTheme
name: bootstrap
displayName: "Bootstrap"
version: "1.0.0"
author: "CodeLibs Project"
minFessVersion: "15.7"
supportedLocales: [en, ja, de, es, fr, ko, pt-BR, zh-CN]
entry: index.html
spaFallback: true
type: static
thumbnail: thumbnail.png

/themes/{name}/... でアセットが配信され、/search /help /profile /cache /chat などのSPA用パスではエントリの index.html が返されます。一方で /admin/ や /api/ などはこれまで通りFess側のルートに渡されるため、管理画面やAPIがSPAに飲み込まれることはありません。

テーマは管理画面に追加された /admin/theme/ から、ZIPでアップロードして管理します。アップロード時にはZipSlipやzip爆弾などへの対策が入っています。有効化は管理画面で theme.default にテーマ名を設定するか、バーチャルホストに紐付けて行います。

Bootstrapリファレンステーマ

標準で、Bootstrap 5ベースのリファレンステーマを同梱しています。これは既存のJSP検索画面をそのまま再現したもので、バニラのES2022モジュールで書かれています。独自テーマを作る場合は、このテーマをコピーして始めるのがおすすめです。

中心となるのが api.js で、これがそのまま使い回せるAPIラッパーになっています。

• init() … GET /ui/config を呼び、設定とCSRFトークンをキャッシュ
• get(path, params) / post(path, body) … エンベロープを検証し、status !== 0 なら ApiError を投げる。POST時はCSRFトークンを自動付与
• sseStream(path, body, onEvent, onError) … /chat/stream 向けのfetchベースのSSE（標準の EventSource はGET限定でCSRFヘッダーを送れないため独自実装）

チャットのストリーミングはこんな感じで使えます。

import * as api from "./api.js";

const ctrl = api.sseStream("/chat/stream", { q: "質問内容" }, (event) => {
  if (event.type === "chunk") bubble.textContent += event.data.content ?? "";
  if (event.type === "done")  ctrl.abort();
}, (err) => console.error(err));

なお、テーマ内では動的な文字列の innerHTML を使わず、検索結果カードやファセット、ページネーションなどはすべて document.createElement と textContent で組み立てています。XSS対策として、独自テーマでもこの方針を踏襲することをおすすめします。

検索画面を自作する流れ

独自の検索画面を作る場合は、ざっくり以下の流れになります。

1. 同梱の bootstrap テーマのディレクトリをコピーし、theme.yml の name を変更する
2. index.html（Bootstrap 5 + セマンティックなHTML）と styles.css、各JSモジュールを編集する。エンベロープ・CSRF・SSEの処理は api.js をそのまま使い回せる
3. ZIPにまとめて /admin/theme/ からアップロードし、有効化する
4. SPAは api.init() → GET /ui/config（匿名）で起動し、機能フラグとCSRFトークンを読み込んでから /api/v2 を通して検索・認証・お気に入り・チャットを動かす

v1 APIについての注意

今回の変更にあわせて、従来の /api/v1 のJSON検索APIとチャットAPIはFess本体から削除し、fess-webapp-v1-api という別プラグインに切り出しました。これは破壊的変更になります。新規の連携は /api/v2 を対象にしてください。

まとめ

API v2と静的テーマ機能により、FessをヘッドレスなバックエンドとしてHTML/CSS/JSだけで検索画面を構築できるようになりました。同梱のBootstrapテーマをベースに、自分のサイトに合わせた検索画面を作ってみてください。

Fessではユーザーパスワードの保存形式を、これまでのソルトなしSHA-256（1ラウンド）から、Spring Security v5.8互換のBCryptベースの形式へと刷新しました。既存の環境を止めることなく、ログインをきっかけに新形式へ段階的に移行できるようになっています。

変更の背景

これまでのFessはパスワードを sha256(plain) の16進文字列としてそのまま保存していました。ソルトがなくラウンド数も1回のため、万が一パスワードハッシュが漏洩した場合にレインボーテーブルやGPUによる総当たりで平文を復元されるリスクがありました。今回の対応では、保存形式を {bcrypt}$2a$10$... に切り替え、ログインごとに古い形式を新形式へ置き換える仕組みを導入しています。

パスワードハッシュ化の刷新

BCryptへの移行

新たに PasswordHashHelper （org.codelibs.fess.helper.PasswordHashHelper）を追加しました。ComponentUtil.getPasswordHashHelper() 経由で取得し、encode / matches / upgradeEncoding という公開APIを通して利用します。

保存形式にはSpring Securityの DelegatingPasswordEncoder と互換性のある {bcrypt} プレフィクス付きの文字列を採用しました。将来的にアルゴリズムを切り替える場合も、プレフィクスを見ることで旧方式と新方式を混在させたまま検証できます。

jBCryptの同梱

新規のMaven依存は追加せず、jBCrypt v0.4（ISCライセンス）を org.codelibs.fess.crypto.bcrypt.BCrypt としてソースに同梱しました。NOTICEファイルおよびlicense-plugin・formatter-pluginの除外リストもあわせて更新しています。jBCrypt 0.4は $2a$ のみをサポートし、他システムで使われる $2b$ / $2y$ は受け付けません。

既存ハッシュの互換性

プレフィクスのないレガシーな値は、app.digest.algorithm の設定（sha256 / sha512 / md5）に従って小文字16進で比較します。比較は MessageDigest.isEqual による定数時間比較で行い、未知の {id} プレフィクスや不正な値は常に false を返します。

認証フローの変更

FessLoginAssist.doAuthenticateLocal では、これまで「ユーザー名＋ハッシュ済みパスワード」でDBを引いていた処理を、「ユーザー名のみで引いて PasswordHashHelper.matches で照合する」形に変更しました。BCryptはレコードごとにソルトを持つため、事前にハッシュを計算してWHERE句に入れるやり方は使えないためです。

ユーザー不在・null・レガシーhex・未知プレフィクスなどの失敗経路はすべて、applyTimingPadding でダミーのBCrypt検証を1回走らせ、成功時と同じ処理コストがかかるようにしています。これによりユーザーの存在有無が応答時間の差から推測されるタイミング攻撃を防いでいます。

ログイン時の遅延リハッシュ

既存ユーザーの旧形式パスワードは、ログイン成功のタイミングで自動的にBCryptへ置き換わります。この処理は app.password.upgrade.enabled=true（デフォルト有効）かつ upgradeEncoding が true を返した場合のみ走ります。

書き込みには UserService.updateStoredPasswordHash(username, expectedCurrentHash, newEncodedPassword) を新設し、AuthenticationManager を経由しない専用のリハッシュパスとしました。LDAPやSSOなど外部で管理されているユーザーには影響を与えないためです。

更新はOpenSearchの楽観的並行制御で原子性を担保しており、読み出し時の _seq_no / _primary_term を IndexRequestBuilder.setIfSeqNo / setIfPrimaryTerm に伝搬させています。バージョン競合はDEBUGレベルでログ出力するにとどめ、ログインそのものは成功扱いのままとします。

書き込みパスの整理

UserService.changePassword、AdminUserAction.getUser、初期管理ユーザーをブートストラップする SearchEngineClient では、ComponentUtil.getPasswordHashHelper().encode(plain) を直接呼ぶように変更しました。これにより UserService から FessLoginAssist への不自然な依存を取り除いています。

新たなコードからパスワードを書き込む場合も、FessLoginAssist.encryptPassword は使わず PasswordHashHelper.encode を呼ぶようにしてください。

新しい設定項目

fess_config.properties に以下の設定を追加しました。

• app.password.algorithm=bcrypt : 新規書き込み時のアルゴリズム
• app.password.bcrypt.cost=10 : BCryptのコストパラメータ
• app.password.upgrade.enabled=true : 旧形式からの遅延リハッシュの有効化

app.digest.algorithm はレガシーハッシュの検証用として残していますが、今後は新規書き込みには使われません。

ダウングレード時の注意

本変更以降、保存されるパスワードは {bcrypt}$2a$10$... の形式になります。BCrypt対応前のFessへロールバックするとこれらの値は検証できなくなるため、管理者パスワードのリセットが必要になります。運用でダウングレードを想定する場合はリリースノートでの周知と、手順の準備をおすすめします。

スキーマやAPI、i18nリソースへの変更はありません。

詳細

詳細はPR #3116を参照してください。