bitbank-lab-mcp 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +32 -10
- package/bin/bitbank-lab-mcp.js +8 -1
- package/lib/asset-code.ts +54 -0
- package/lib/bounded-expiring-set.ts +330 -0
- package/lib/calendar.ts +266 -0
- package/lib/datetime.ts +21 -0
- package/lib/http.ts +63 -2
- package/lib/logger.ts +59 -8
- package/lib/pair-code.ts +88 -0
- package/lib/pairs.ts +58 -0
- package/lib/tickers.ts +6 -1
- package/lib/tx-archive.ts +34 -20
- package/lib/tx-fetch.ts +732 -0
- package/package.json +2 -1
- package/src/env.ts +18 -1
- package/src/handlers/analyzeMyPortfolioHandler.ts +872 -149
- package/src/handlers/detectPatternsHandler.ts +7 -5
- package/src/handlers/detectPatternsViewsHandler.ts +6 -26
- package/src/handlers/getVolatilityMetricsHandler.ts +24 -4
- package/src/handlers/portfolio/calc.ts +876 -110
- package/src/handlers/portfolio/calendar.ts +43 -0
- package/src/handlers/portfolio/fetch.ts +362 -8
- package/src/handlers/portfolio/types.ts +299 -16
- package/src/mcp-apps-meta.ts +45 -0
- package/src/private/config.ts +29 -14
- package/src/private/confirmation.ts +178 -49
- package/src/private/elicitation.ts +194 -38
- package/src/private/request-state.ts +135 -22
- package/src/private/schemas.ts +515 -38
- package/src/prompts/intermediate.ts +2 -2
- package/src/prompts/reports.ts +1 -1
- package/src/resources/app-resources.ts +15 -0
- package/src/schema/analysis.ts +77 -5
- package/src/schema/base.ts +154 -0
- package/src/schema/candle-validate.ts +5 -1
- package/src/schema/market-data.ts +177 -25
- package/src/schema/patterns.ts +38 -3
- package/src/server.ts +59 -10
- package/src/tool-definition.ts +13 -0
- package/src/tool-registry.ts +4 -0
- package/src/ui-snapshot-cache.ts +87 -22
- package/tools/analyze_candle_patterns.ts +17 -5
- package/tools/analyze_market_signal.ts +19 -7
- package/tools/analyze_volume_profile.ts +170 -113
- package/tools/detect_macd_cross.ts +13 -2
- package/tools/detect_patterns.ts +13 -23
- package/tools/get_candles.ts +108 -129
- package/tools/get_flow_metrics.ts +478 -276
- package/tools/get_transactions.ts +136 -33
- package/tools/get_ui_snapshot.ts +26 -4
- package/tools/get_volatility_metrics.ts +15 -4
- package/tools/patterns/period.ts +122 -0
- package/tools/private/cancel_order.ts +41 -21
- package/tools/private/cancel_orders.ts +40 -18
- package/tools/private/create_order.ts +43 -39
- package/tools/private/get_margin_positions.ts +13 -2
- package/tools/private/get_margin_status.ts +8 -2
- package/tools/private/get_margin_trade_history.ts +8 -3
- package/tools/private/get_my_assets.ts +7 -1
- package/tools/private/get_my_deposit_withdrawal.ts +7 -2
- package/tools/private/get_my_orders.ts +4 -2
- package/tools/private/get_my_trade_history.ts +5 -1
- package/tools/private/get_order.ts +10 -5
- package/tools/private/get_orders_info.ts +5 -2
- package/tools/private/preview_cancel_order.ts +42 -24
- package/tools/private/preview_cancel_orders.ts +41 -24
- package/tools/private/preview_order.ts +42 -24
- package/tools/trading_process/lib/fetch_candles.ts +18 -8
- package/ui/cancel-confirm/dist/cancel-confirm.html +44 -44
- package/ui/order-confirm/dist/order-confirm.html +33 -33
package/README.md
CHANGED
|
@@ -115,7 +115,7 @@ nvm/volta などのバージョン管理ツールをお使いの方には特に
|
|
|
115
115
|
|
|
116
116
|
**C. 取引注文・注文キャンセル実行(要 API キー):**
|
|
117
117
|
|
|
118
|
-
B
|
|
118
|
+
B に加えて、対応ホスト上での発注・注文キャンセルまで実行。実行前に必ず確認ステップ(preview → ユーザーの明示確認)が入ります。
|
|
119
119
|
|
|
120
120
|
```json
|
|
121
121
|
{
|
|
@@ -125,8 +125,7 @@ B に加えて、AI からの発注・注文キャンセルまで実行。実行
|
|
|
125
125
|
"args": ["-y", "bitbank-lab-mcp"],
|
|
126
126
|
"env": {
|
|
127
127
|
"BITBANK_API_KEY": "your_api_key",
|
|
128
|
-
"BITBANK_API_SECRET": "your_api_secret"
|
|
129
|
-
"BITBANK_TRUST_HOST_APPROVAL": "1"
|
|
128
|
+
"BITBANK_API_SECRET": "your_api_secret"
|
|
130
129
|
}
|
|
131
130
|
}
|
|
132
131
|
}
|
|
@@ -137,7 +136,30 @@ B に加えて、AI からの発注・注文キャンセルまで実行。実行
|
|
|
137
136
|
>
|
|
138
137
|
> ※ **「出金」権限は有効化しないことを強く推奨します**。本サーバーは出金系ツール未実装のため不要です。
|
|
139
138
|
|
|
140
|
-
`
|
|
139
|
+
発注・取消の実行には**ユーザーの明示確認が必須**です。確認トークンは `content` / `structuredContent` に載らないため、LLM が preview 応答から直接 execute することはできません。旧 `BITBANK_TRUST_HOST_APPROVAL` オプトイン(iframe に token を `structuredContent` で載せる妥協モード)はセキュリティ上撤去済みで、設定しても無視されます。
|
|
140
|
+
|
|
141
|
+
確認の経路はクライアントによって変わります。
|
|
142
|
+
|
|
143
|
+
| クライアント | 実行経路 |
|
|
144
|
+
|---|---|
|
|
145
|
+
| elicitation / MRTR 対応 | ネイティブ確認ダイアログで完結(**第一選択**。追加設定不要) |
|
|
146
|
+
| MCP Apps UI 対応(Claude Desktop 等) | `BITBANK_MCP_APPS_EXECUTE=1` を設定した場合のみ、確認カードのボタンで実行(**既定は無効**) |
|
|
147
|
+
| どちらも非対応 | プレビューのみ。実行は bitbank アプリ/ウェブで |
|
|
148
|
+
|
|
149
|
+
<details>
|
|
150
|
+
<summary><b>⚠️ <code>BITBANK_MCP_APPS_EXECUTE=1</code> を設定する前に読んでください</b></summary>
|
|
151
|
+
|
|
152
|
+
このオプションは、確認トークンをツール結果の `_meta` にのみ載せて iframe へ渡し、確認カードのボタンからの実行を許可します。安全性は「**ホストが `_meta` をモデル(LLM)に渡さない**」という前提に依存します。
|
|
153
|
+
|
|
154
|
+
* **仕様上の保証ではありません。** MCP Apps 仕様の該当記述は "Best Practices" の箇条書きで、MUST / SHOULD を伴いません。適合要件ではなく意図の説明です
|
|
155
|
+
* **ホストのアップデートで壊れても、サーバー側では検知できません。** ホストが `_meta` をモデルコンテキストに含めるようになった瞬間に前提は崩れますが、その変化はサーバーから観測できません。**壊れ方は静かです**
|
|
156
|
+
* この領域は実装が流動的です(`structuredContent` の喪失回帰など、関連トラッカーに 2026-05〜08 の issue が複数)
|
|
157
|
+
|
|
158
|
+
万一トークンが漏れた場合でも、被害は **「直前にプレビューした注文 1 件(一括取消ならプレビュー済みの注文 ID 集合 1 セット)が、60 秒以内に 1 回だけ実行される」** に限定されます。トークンは注文内容に HMAC で束縛されており、攻撃者が金額・数量・ペア・方向を選ぶことはできません。
|
|
159
|
+
|
|
160
|
+
**以上を理解したうえで有効化してください。既定では無効です。** 詳細は [ADR-0007](docs/adr/0007-hitl-confirmation-token-delivery.md)。
|
|
161
|
+
|
|
162
|
+
</details>
|
|
141
163
|
|
|
142
164
|
詳細: [ADR-0007](docs/adr/0007-hitl-confirmation-token-delivery.md) / [Private API ガイド](docs/private-api.md)。
|
|
143
165
|
|
|
@@ -244,7 +266,7 @@ Claude Desktop の UI に表示される名前は `claude_desktop_config.json`
|
|
|
244
266
|
}
|
|
245
267
|
```
|
|
246
268
|
|
|
247
|
-
API キーが不要な場合は `env` ブロックごと削除して OK。セクション 1 の A〜C
|
|
269
|
+
API キーが不要な場合は `env` ブロックごと削除して OK。セクション 1 の A〜C と同様に、取引実行まで使う場合は確認フローに対応したクライアントが必要です(旧 `BITBANK_TRUST_HOST_APPROVAL` は不要・無効です)。
|
|
248
270
|
|
|
249
271
|
#### Claude Code(CLI から登録する場合)
|
|
250
272
|
|
|
@@ -376,11 +398,11 @@ API キーは [bitbank 設定画面](https://app.bitbank.cc/account/api) で発
|
|
|
376
398
|
| ポートフォリオ | `analyze_my_portfolio` | 損益分析・パフォーマンス | 参照 |
|
|
377
399
|
| 入出金 | `get_my_deposit_withdrawal` | 入出金履歴 | 参照 |
|
|
378
400
|
| 信用取引 | `get_margin_status`, `get_margin_positions`, `get_margin_trade_history` | 証拠金・ポジション・約定履歴 | 参照 |
|
|
379
|
-
| 発注 | `preview_order
|
|
380
|
-
| キャンセル | `preview_cancel_order
|
|
381
|
-
| 一括キャンセル | `preview_cancel_orders
|
|
401
|
+
| 発注 | `preview_order`(→ ユーザー確認) | ユーザー明示確認後に発注 | 取引 |
|
|
402
|
+
| キャンセル | `preview_cancel_order`(→ ユーザー確認) | ユーザー明示確認後にキャンセル | 取引 |
|
|
403
|
+
| 一括キャンセル | `preview_cancel_orders`(→ ユーザー確認) | ユーザー明示確認後に一括キャンセル | 取引 |
|
|
382
404
|
|
|
383
|
-
取引操作(発注・キャンセル)は **preview →
|
|
405
|
+
取引操作(発注・キャンセル)は **preview → ユーザーの明示確認**が必須です。確認トークンは `content` / `structuredContent` に載らず、`create_order` / `cancel_order` / `cancel_orders` を MCP `tools/call` から直接呼んでもサーバー側で拒否されます。
|
|
384
406
|
|
|
385
407
|
詳細: [docs/private-api.md](docs/private-api.md)
|
|
386
408
|
|
|
@@ -420,7 +442,7 @@ npx @modelcontextprotocol/inspector -- npx -y bitbank-lab-mcp
|
|
|
420
442
|
```
|
|
421
443
|
ソースコードから動かす場合は `npx @modelcontextprotocol/inspector -- tsx src/server.ts`([開発者向け](#開発者向けソースから起動) を参照)。
|
|
422
444
|
|
|
423
|
-
**Q. 当日の約定(フロー)データが少ない・古い時間帯が取れない** bitbank 側の仕様です。約定履歴の日付アーカイブ(`/transactions/{YYYYMMDD}`)は **UTC 暦日単位**で、当該 UTC 日の完了後(日本時間 9:00 以降、さらに公開遅延あり)にのみ公開されます。進行中の UTC 日の約定は直近約 60 件(latest)しか取得できないため、`get_flow_metrics` 等では当日区間のカバレッジが限定的になります(結果に warning として明示されます)。ローソク足(`get_candles`)は進行中の UTC
|
|
445
|
+
**Q. 当日の約定(フロー)データが少ない・古い時間帯が取れない** bitbank 側の仕様です。約定履歴の日付アーカイブ(`/transactions/{YYYYMMDD}`)は **UTC 暦日単位**で、当該 UTC 日の完了後(日本時間 9:00 以降、さらに公開遅延あり)にのみ公開されます。進行中の UTC 日の約定は直近約 60 件(latest)しか取得できないため、`get_flow_metrics` 等では当日区間のカバレッジが限定的になります(結果に warning として明示されます)。ローソク足(`get_candles`)は進行中の UTC 日でもリアルタイムで取得できます。<br>なお**公開済みの過去区間**であれば、`get_flow_metrics` / `analyze_volume_profile` の `since` / `until`(オフセット付き ISO8601、最大 7 日)でその区間の**全件**を集計できます(例: `since=2026-08-01T00:00:00Z`, `until=2026-08-02T00:00:00Z` で UTC 8/1 の 1 日ぶん)。件数上限による切り捨ては起きません。
|
|
424
446
|
|
|
425
447
|
## トラブルシューティング
|
|
426
448
|
|
package/bin/bitbank-lab-mcp.js
CHANGED
|
@@ -5,13 +5,20 @@ import { dirname, resolve } from 'node:path';
|
|
|
5
5
|
import { fileURLToPath, pathToFileURL } from 'node:url';
|
|
6
6
|
|
|
7
7
|
const __dirname = dirname(fileURLToPath(import.meta.url));
|
|
8
|
-
const
|
|
8
|
+
const packageRoot = resolve(__dirname, '..');
|
|
9
|
+
const serverPath = resolve(packageRoot, 'src', 'server.ts');
|
|
9
10
|
|
|
10
11
|
const require = createRequire(import.meta.url);
|
|
11
12
|
const tsxImportUrl = pathToFileURL(require.resolve('tsx')).href;
|
|
12
13
|
|
|
14
|
+
// cwd をパッケージルートに固定する。MCP ホスト(Claude Desktop 等)が spawn する際の
|
|
15
|
+
// cwd は制御できず、macOS では `/` になる。継承すると cwd 相対のパス解決がすべて
|
|
16
|
+
// `/` 基準になり、ログ出力(`lib/logger.ts`)と `.env` 読み込み(`src/env.ts`)が
|
|
17
|
+
// 黙って失敗する。両モジュール側でもパッケージルート基準に解決しているが、
|
|
18
|
+
// 起点をここで揃えておけば今後 cwd 相対を足しても壊れない。
|
|
13
19
|
const child = spawn(process.execPath, ['--import', tsxImportUrl, serverPath], {
|
|
14
20
|
stdio: 'inherit',
|
|
21
|
+
cwd: packageRoot,
|
|
15
22
|
});
|
|
16
23
|
|
|
17
24
|
for (const sig of ['SIGINT', 'SIGTERM']) {
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* asset コード正規化ユーティリティ。
|
|
3
|
+
*
|
|
4
|
+
* bitbank API が返す通貨コード(`assets[].asset` / `deposits[].asset` /
|
|
5
|
+
* `withdrawals[].asset`)を **取得境界で小文字へ揃える**ための単一実装。
|
|
6
|
+
*
|
|
7
|
+
* リポジトリ全体が「API が返す asset は小文字」という前提の上に立っており、
|
|
8
|
+
* 生の `asset` を小文字リテラル(`'jpy'`)と比較する、あるいは Map のキーに使う
|
|
9
|
+
* 箇所が 20 箇所以上ある(`portfolio/calc.ts` の JPY 判定・holdings キー・
|
|
10
|
+
* `prices.get(asset)` 等)。大文字が 1 つでも紛れ込むと、`JPY` が「価格を引けない
|
|
11
|
+
* 暗号資産」として純入出金から落ちる/`BTC` と `btc` で保有キーが割れて二重計上に
|
|
12
|
+
* なる、といった破綻が同時に起きる。
|
|
13
|
+
*
|
|
14
|
+
* これは**防御的正規化**であり、現行 API は小文字を返す(公式 docs の JSON 例は
|
|
15
|
+
* `"asset": "jpy"`、`docs/internal/bitbank-api-fields.md` 参照)。前提をコードに
|
|
16
|
+
* 明文化し、破れたときに数値が壊れないようにするのが目的。
|
|
17
|
+
*
|
|
18
|
+
* **消費側(`portfolio/calc.ts` 等)に `.toLowerCase()` を撒かないこと。**
|
|
19
|
+
* 正規化は取得境界(`portfolio/fetch.ts` / `/v1/user/assets` の取り込み)に集約し、
|
|
20
|
+
* どこで担保されているかを 1 箇所に保つ。
|
|
21
|
+
*
|
|
22
|
+
* ユーザー入力の pair 正規化(`lib/validate.ts` の `normalizePair`)とは別レイヤー。
|
|
23
|
+
* 混ぜないこと(あちらは入力の受け口、こちらは API レスポンスの受け口)。
|
|
24
|
+
*
|
|
25
|
+
* API が返す **pair シンボル**の取得境界正規化は姉妹モジュール `lib/pair-code.ts`。
|
|
26
|
+
* pair から導出した asset(`replace('_jpy', '')`)は本モジュールが担保する小文字空間に
|
|
27
|
+
* 乗る必要があるため、両者は同じ境界方針で揃えてある。
|
|
28
|
+
*/
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* API 由来の asset コードを小文字へ正規化する。
|
|
32
|
+
*
|
|
33
|
+
* 前後の空白も落とす(`normalizePair` と同方針)。asset コードは英数字のみのため、
|
|
34
|
+
* ロケール依存の `toLocaleLowerCase` ではなく `toLowerCase` を使う。
|
|
35
|
+
*/
|
|
36
|
+
export function normalizeAssetCode(raw: string): string {
|
|
37
|
+
return raw.trim().toLowerCase();
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* API レスポンスのレコード配列について `asset` フィールドのみを正規化した配列を返す。
|
|
42
|
+
*
|
|
43
|
+
* 既に小文字(=現行 API の実挙動)なら**元のオブジェクト参照をそのまま通す**ので、
|
|
44
|
+
* 既存レスポンスに対しては実質ノーオペ(出力は 1 バイトも変わらない)。
|
|
45
|
+
*/
|
|
46
|
+
export function normalizeAssetCodes<T extends { asset: string }>(records: readonly T[]): T[] {
|
|
47
|
+
return records.map((record) => {
|
|
48
|
+
// レスポンス不正で asset が欠けていても取得層で throw させない(防御)。
|
|
49
|
+
// 消費側では従来どおり「'jpy' でない未知資産」として扱われる。
|
|
50
|
+
if (typeof record.asset !== 'string') return record;
|
|
51
|
+
const asset = normalizeAssetCode(record.asset);
|
|
52
|
+
return asset === record.asset ? record : { ...record, asset };
|
|
53
|
+
});
|
|
54
|
+
}
|
|
@@ -0,0 +1,330 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* TTL + 件数上限つきの「使用済み記録」セット(replay ガード用の共通データ構造)。
|
|
3
|
+
*
|
|
4
|
+
* 使用済みの confirmation token(`src/private/confirmation.ts`)や requestState の nonce
|
|
5
|
+
* (`src/private/request-state.ts`)のように、**一度使ったキーを TTL の間だけ覚えておき、
|
|
6
|
+
* 再提示を拒否する**用途のために切り出したもの。
|
|
7
|
+
*
|
|
8
|
+
* 設計上の最重要ルール — **生存エントリを追い出さない**:
|
|
9
|
+
* 容量を空けるために未期限切れのエントリを LRU 等で退避すると、その token / nonce は
|
|
10
|
+
* 「未使用」状態に巻き戻り、replay が黙って通る。メモリ上限のためにワンタイム性を
|
|
11
|
+
* 犠牲にしてはいけないので、容量到達時は
|
|
12
|
+
* 1. 期限切れエントリを purge する(古い=挿入順の先頭側から)
|
|
13
|
+
* 2. それでも空きが無ければ `add` を失敗させる
|
|
14
|
+
* の順で処理し、呼び出し側に実行を拒否させる(fail-closed)。
|
|
15
|
+
*
|
|
16
|
+
* ワンタイム性の保証範囲:
|
|
17
|
+
* 保証されるのは `expiresAtMs` までの間だけ。期限切れ後は記録が消えるため、
|
|
18
|
+
* 同じキーを再び `add` できる。呼び出し側は「記録の有無」とは別に、token / nonce 自身の
|
|
19
|
+
* 有効期限も必ず検証すること(`validateToken` が期限チェックを先に行うのと同じ理由)。
|
|
20
|
+
*
|
|
21
|
+
* 非有限のタイムスタンプ:
|
|
22
|
+
* `expiresAtMs` は confirmation フローでクライアントを往復しうる値なので、外部由来として扱う。
|
|
23
|
+
* 非有限値(NaN / ±Infinity)は**状態を一切変更する前に**弾き、`invalid_expiry` で拒否する。
|
|
24
|
+
* `nowMs` は呼び出し側の時計(既定 `Date.now()`)なので、非有限値はプログラミングエラーとして
|
|
25
|
+
* `TypeError` を投げる。どちらも黙って劣化させると replay が通る(理由は各メソッドのコメント)。
|
|
26
|
+
*
|
|
27
|
+
* ログ:
|
|
28
|
+
* このモジュールは key の本文を保持するだけで、**どこにも出力しない**。
|
|
29
|
+
* token / nonce は `.claude/rules/sensitive-data.md` の CRITICAL 分類にあたるため、
|
|
30
|
+
* 呼び出し側もログには `stats()` が返す件数系のメタ情報のみを記録すること。
|
|
31
|
+
*
|
|
32
|
+
* 使い方:
|
|
33
|
+
* const used = new BoundedExpiringSet();
|
|
34
|
+
* used.startCleanupTimer();
|
|
35
|
+
* const res = used.add(token, expiresAt);
|
|
36
|
+
* if (!res.added) return reject(res.reason);
|
|
37
|
+
*/
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* 記録件数の既定上限。
|
|
41
|
+
*
|
|
42
|
+
* 算出根拠 — TTL × 想定ピークレート:
|
|
43
|
+
* - 保持期間: 最長 300 秒。confirmation token は既定 60 秒(`ORDER_CONFIRM_TTL_MS`)で
|
|
44
|
+
* 上限 300 秒(`MAX_TTL_MS`)、requestState の nonce は 300 秒(`REQUEST_STATE_TTL_SECONDS`)。
|
|
45
|
+
* - 想定ピーク確認レート: 20 件/秒。HITL 確認は人手起点なので実運用では 1 件/秒にも届かないが、
|
|
46
|
+
* 自動化クライアントの連投を見込んで 20 倍のマージンを取る。
|
|
47
|
+
* → 300 秒 × 20 件/秒 = 6,000 件。切り上げて 10,000 件。
|
|
48
|
+
*
|
|
49
|
+
* メモリ概算 — 1 エントリあたり:
|
|
50
|
+
* - key: HMAC-SHA256 の hex = 64 文字 ≈ 64B + 文字列ヘッダ ≈ 24B → 約 88B
|
|
51
|
+
* (nonce は 32 文字なので約半分。長い方に合わせて見積もる)
|
|
52
|
+
* - value: expiresAt。ms epoch は Smi 範囲外なので heap number 扱い → 約 16B
|
|
53
|
+
* - Map のエントリ配列 + ハッシュ表(負荷率の余白込み) → 約 96B
|
|
54
|
+
* → 合計 約 200B/件。10,000 件で 約 2MB。`MAX_ENTRIES_CEILING` の 100,000 件でも 約 20MB。
|
|
55
|
+
*/
|
|
56
|
+
export const DEFAULT_MAX_ENTRIES = 10_000;
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* 上限値の clamp 先(≈20MB 相当)。
|
|
60
|
+
* 環境変数やコンストラクタ引数でこれを超える値を渡してもここで頭打ちにする。
|
|
61
|
+
*/
|
|
62
|
+
export const MAX_ENTRIES_CEILING = 100_000;
|
|
63
|
+
|
|
64
|
+
/** 既定の定期 purge 間隔: 60秒(`src/private/confirmation.ts` の `CLEANUP_INTERVAL_MS` と揃える) */
|
|
65
|
+
export const DEFAULT_PURGE_INTERVAL_MS = 60_000;
|
|
66
|
+
|
|
67
|
+
/** 件数上限を上書きする環境変数名。不正値は `DEFAULT_MAX_ENTRIES` にフォールバックする。 */
|
|
68
|
+
export const MAX_ENTRIES_ENV = 'REPLAY_GUARD_MAX_ENTRIES';
|
|
69
|
+
|
|
70
|
+
/** `add` が失敗した理由 */
|
|
71
|
+
export type AddRejectReason =
|
|
72
|
+
/** 同じ key が生存中の記録として既に存在する(= replay) */
|
|
73
|
+
| 'already_recorded'
|
|
74
|
+
/** 件数上限に達しており、期限切れを purge しても空きを作れなかった */
|
|
75
|
+
| 'capacity_exceeded'
|
|
76
|
+
/** `expiresAtMs` が非有限値(NaN / ±Infinity)だった */
|
|
77
|
+
| 'invalid_expiry';
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* `add` の結果。
|
|
81
|
+
*
|
|
82
|
+
* 判別可能ユニオンにしてあるので、`reason` を読むには必ず `added` で絞り込む必要がある。
|
|
83
|
+
* `if (!res.added)` を書かずに理由を参照することはできない(呼び出し側が黙って握り潰せない)。
|
|
84
|
+
*/
|
|
85
|
+
export type AddResult = { readonly added: true } | { readonly added: false; readonly reason: AddRejectReason };
|
|
86
|
+
|
|
87
|
+
/** 観測用カウンタ。key の本文は一切含まない。 */
|
|
88
|
+
export interface BoundedExpiringSetStats {
|
|
89
|
+
/** 現在の記録件数(期限切れが残っている場合は含む) */
|
|
90
|
+
size: number;
|
|
91
|
+
/** 有効な件数上限(clamp 適用後) */
|
|
92
|
+
maxEntries: number;
|
|
93
|
+
/** 除去した期限切れエントリの累計 */
|
|
94
|
+
purgedTotal: number;
|
|
95
|
+
/** 容量超過で拒否した `add` の累計 */
|
|
96
|
+
rejectedTotal: number;
|
|
97
|
+
/** 非有限の `expiresAtMs` で拒否した `add` の累計(改竄・呼び出し側バグの検知用) */
|
|
98
|
+
invalidExpiryTotal: number;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
export interface BoundedExpiringSetOptions {
|
|
102
|
+
/**
|
|
103
|
+
* 件数上限。省略時は環境変数 `REPLAY_GUARD_MAX_ENTRIES`、それも無ければ `DEFAULT_MAX_ENTRIES`。
|
|
104
|
+
* 非有限値・1 未満はデフォルトへフォールバックし、`MAX_ENTRIES_CEILING` で clamp する。
|
|
105
|
+
*/
|
|
106
|
+
maxEntries?: number;
|
|
107
|
+
/** 定期 purge の間隔(ms)。非有限値・0 以下はデフォルトへフォールバック。 */
|
|
108
|
+
purgeIntervalMs?: number;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** 非有限値・1 未満はデフォルトへ、上限超過は clamp(`getTtlMs` と同じ扱い) */
|
|
112
|
+
function normalizeMaxEntries(value: number | undefined): number {
|
|
113
|
+
if (value == null || !Number.isFinite(value) || value < 1) return DEFAULT_MAX_ENTRIES;
|
|
114
|
+
return Math.min(Math.floor(value), MAX_ENTRIES_CEILING);
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** 環境変数の生値を数値化する。未設定・空文字は undefined(=デフォルト採用) */
|
|
118
|
+
function envMaxEntries(): number | undefined {
|
|
119
|
+
const raw = process.env[MAX_ENTRIES_ENV];
|
|
120
|
+
if (!raw) return undefined;
|
|
121
|
+
// NaN もここを通すが normalizeMaxEntries がデフォルトへ落とす
|
|
122
|
+
return Number(raw);
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
function normalizePurgeInterval(value: number | undefined): number {
|
|
126
|
+
if (value == null || !Number.isFinite(value) || value <= 0) return DEFAULT_PURGE_INTERVAL_MS;
|
|
127
|
+
return value;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* `nowMs` が非有限だと期限比較(`nowMs > expiresAt` / `nowMs <= expiresAt`)が全て false になり、
|
|
132
|
+
* 「生存エントリを期限切れとみなして削除 → 同じ key を再記録できる」= replay が黙って通る。
|
|
133
|
+
* `nowMs` は呼び出し側の時計(既定 `Date.now()`)でありユーザー入力ではないので、
|
|
134
|
+
* 劣化させずプログラミングエラーとして投げる。メッセージに key は含めない。
|
|
135
|
+
*/
|
|
136
|
+
function assertFiniteNow(nowMs: number, method: string): void {
|
|
137
|
+
if (!Number.isFinite(nowMs)) {
|
|
138
|
+
throw new TypeError(`BoundedExpiringSet.${method}: nowMs must be a finite number`);
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
export class BoundedExpiringSet {
|
|
143
|
+
/**
|
|
144
|
+
* key → expiresAt(ms)。
|
|
145
|
+
*
|
|
146
|
+
* Map は挿入順を保持するので、**TTL が呼び出し間で一定であれば挿入順 = 期限順**になる。
|
|
147
|
+
* この性質を使って通常経路では先頭側だけを走査し(`purgeExpiredPrefix`)、最初に
|
|
148
|
+
* 生存エントリへ当たった時点で打ち切る。TTL が不揃いな呼び出し方をされると先頭走査では
|
|
149
|
+
* 取りこぼすため、容量到達時のみ全走査(`purgeExpired`)にフォールバックする。
|
|
150
|
+
*/
|
|
151
|
+
private readonly store = new Map<string, number>();
|
|
152
|
+
|
|
153
|
+
private readonly maxEntriesValue: number;
|
|
154
|
+
private readonly purgeIntervalMs: number;
|
|
155
|
+
private cleanupTimerId: ReturnType<typeof setInterval> | null = null;
|
|
156
|
+
private purgedTotal = 0;
|
|
157
|
+
private rejectedTotal = 0;
|
|
158
|
+
private invalidExpiryTotal = 0;
|
|
159
|
+
|
|
160
|
+
constructor(opts: BoundedExpiringSetOptions = {}) {
|
|
161
|
+
this.maxEntriesValue = normalizeMaxEntries(opts.maxEntries ?? envMaxEntries());
|
|
162
|
+
this.purgeIntervalMs = normalizePurgeInterval(opts.purgeIntervalMs);
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/** 有効な件数上限(clamp 適用後) */
|
|
166
|
+
get maxEntries(): number {
|
|
167
|
+
return this.maxEntriesValue;
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* key を使用済みとして記録する。
|
|
172
|
+
*
|
|
173
|
+
* - 未記録(または記録が期限切れ)かつ空きがある → `{ added: true }`
|
|
174
|
+
* - 生存中の記録が既にある → `{ added: false, reason: 'already_recorded' }`(replay)
|
|
175
|
+
* - 期限切れを purge しても空きが作れない → `{ added: false, reason: 'capacity_exceeded' }`
|
|
176
|
+
* - `expiresAtMs` が非有限値 → `{ added: false, reason: 'invalid_expiry' }`(状態は変更しない)
|
|
177
|
+
*
|
|
178
|
+
* 容量を空けるために生存エントリを追い出すことはない。呼び出し側は
|
|
179
|
+
* `added === false` の場合、理由を問わず対象の操作を拒否すること。
|
|
180
|
+
*
|
|
181
|
+
* @param key - 記録するキー(token / nonce 等)。ログには出さない。
|
|
182
|
+
* @param expiresAtMs - 記録の有効期限(epoch ms)。有限値のみ受け付ける。過去を渡した場合は
|
|
183
|
+
* 直後に期限切れ扱いになる。TTL の上限クランプは呼び出し側の責務
|
|
184
|
+
* (`confirmation.ts` の `MAX_TTL_MS` 等)で、ここでは長さの妥当性までは見ない。
|
|
185
|
+
* @param nowMs - 現在時刻(テスト用にオーバーライド可能)。非有限値は `TypeError`。
|
|
186
|
+
* @throws {TypeError} `nowMs` が非有限値の場合
|
|
187
|
+
*/
|
|
188
|
+
add(key: string, expiresAtMs: number, nowMs: number = Date.now()): AddResult {
|
|
189
|
+
assertFiniteNow(nowMs, 'add');
|
|
190
|
+
|
|
191
|
+
// 非有限の expiresAt は「状態を触る前」に弾く(下の purgeExpiredPrefix より必ず先)。
|
|
192
|
+
// NaN … 全比較が false になるため has() / purgeExpired() からは「永久に生存」に見える一方、
|
|
193
|
+
// purgeExpiredPrefix では期限切れ扱いで削除される。判定が経路ごとに食い違い、
|
|
194
|
+
// 記録済みのはずの key が黙って消えて replay が通る。
|
|
195
|
+
// Infinity … 期限切れにならず容量を専有し続ける。さらに先頭走査がそこで打ち切られるため、
|
|
196
|
+
// 高速パスが恒久的に機能しなくなる。
|
|
197
|
+
if (!Number.isFinite(expiresAtMs)) {
|
|
198
|
+
this.invalidExpiryTotal++;
|
|
199
|
+
return { added: false, reason: 'invalid_expiry' };
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
// 通常経路の掃除。先頭が生存していれば比較 1 回で抜けるので、
|
|
203
|
+
// エントリ数に比例した CPU 消費(= CPU 側の攻撃面)を避けられる。
|
|
204
|
+
this.purgeExpiredPrefix(nowMs);
|
|
205
|
+
|
|
206
|
+
const existing = this.store.get(key);
|
|
207
|
+
if (existing != null) {
|
|
208
|
+
if (nowMs <= existing) return { added: false, reason: 'already_recorded' };
|
|
209
|
+
// 期限切れの残骸。ワンタイム性は TTL 内でのみ保証するので、消して再記録を許す。
|
|
210
|
+
this.store.delete(key);
|
|
211
|
+
this.purgedTotal++;
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
if (this.store.size >= this.maxEntriesValue) {
|
|
215
|
+
// 先頭走査で足りなかった(TTL が不揃い等)→ 全走査で最後の空きを探す
|
|
216
|
+
this.purgeExpired(nowMs);
|
|
217
|
+
if (this.store.size >= this.maxEntriesValue) {
|
|
218
|
+
// 生存エントリの追い出しはしない。ここで失敗させ、呼び出し側に拒否させる。
|
|
219
|
+
this.rejectedTotal++;
|
|
220
|
+
return { added: false, reason: 'capacity_exceeded' };
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
this.store.set(key, expiresAtMs);
|
|
225
|
+
return { added: true };
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
/**
|
|
229
|
+
* key が生存中の記録として存在するか。期限切れは「存在しない」として扱い、
|
|
230
|
+
* 該当エントリはこの場で除去する(アクセス時 purge、O(1))。
|
|
231
|
+
*
|
|
232
|
+
* @throws {TypeError} `nowMs` が非有限値の場合
|
|
233
|
+
*/
|
|
234
|
+
has(key: string, nowMs: number = Date.now()): boolean {
|
|
235
|
+
assertFiniteNow(nowMs, 'has');
|
|
236
|
+
const expiresAt = this.store.get(key);
|
|
237
|
+
if (expiresAt == null) return false;
|
|
238
|
+
if (nowMs > expiresAt) {
|
|
239
|
+
this.store.delete(key);
|
|
240
|
+
this.purgedTotal++;
|
|
241
|
+
return false;
|
|
242
|
+
}
|
|
243
|
+
return true;
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* 期限切れエントリを全走査で除去し、除去件数を返す。
|
|
248
|
+
*
|
|
249
|
+
* @throws {TypeError} `nowMs` が非有限値の場合
|
|
250
|
+
*/
|
|
251
|
+
purgeExpired(nowMs: number = Date.now()): number {
|
|
252
|
+
assertFiniteNow(nowMs, 'purgeExpired');
|
|
253
|
+
let purged = 0;
|
|
254
|
+
for (const [key, expiresAt] of this.store) {
|
|
255
|
+
if (nowMs > expiresAt) {
|
|
256
|
+
this.store.delete(key);
|
|
257
|
+
purged++;
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
this.purgedTotal += purged;
|
|
261
|
+
return purged;
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
/**
|
|
265
|
+
* 挿入順の先頭側から期限切れを除去し、最初の生存エントリで打ち切る。
|
|
266
|
+
* TTL が一定という前提の下では全期限切れを除去できる(前提が崩れた場合の
|
|
267
|
+
* 取りこぼしは `add` の容量到達時に `purgeExpired` がカバーする)。
|
|
268
|
+
*
|
|
269
|
+
* 事前条件: `nowMs` が有限であること(呼び出し元の `add` が検証済み)。
|
|
270
|
+
* 格納値も `add` が有限値のみ通すので、比較が NaN で崩れることはない。
|
|
271
|
+
*/
|
|
272
|
+
private purgeExpiredPrefix(nowMs: number): number {
|
|
273
|
+
let purged = 0;
|
|
274
|
+
for (const [key, expiresAt] of this.store) {
|
|
275
|
+
// 先頭が生存 → 以降も生存(TTL 一定前提)
|
|
276
|
+
if (nowMs <= expiresAt) break;
|
|
277
|
+
this.store.delete(key);
|
|
278
|
+
purged++;
|
|
279
|
+
}
|
|
280
|
+
this.purgedTotal += purged;
|
|
281
|
+
return purged;
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
/** 現在の記録件数(期限切れが残っている場合は含む) */
|
|
285
|
+
size(): number {
|
|
286
|
+
return this.store.size;
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/** 全記録を破棄する(テスト用 / プロセス内リセット用)。累計カウンタは保持する。 */
|
|
290
|
+
clear(): void {
|
|
291
|
+
this.store.clear();
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/** 観測用カウンタのスナップショット。key の本文は含まない。 */
|
|
295
|
+
stats(): BoundedExpiringSetStats {
|
|
296
|
+
return {
|
|
297
|
+
size: this.store.size,
|
|
298
|
+
maxEntries: this.maxEntriesValue,
|
|
299
|
+
purgedTotal: this.purgedTotal,
|
|
300
|
+
rejectedTotal: this.rejectedTotal,
|
|
301
|
+
invalidExpiryTotal: this.invalidExpiryTotal,
|
|
302
|
+
};
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
/**
|
|
306
|
+
* 定期 purge を開始する(重複起動しない)。
|
|
307
|
+
* アクセス時 purge だけに頼ると、無アクセス期間のエントリが TTL 超過後も残り続ける。
|
|
308
|
+
*/
|
|
309
|
+
startCleanupTimer(): void {
|
|
310
|
+
if (this.cleanupTimerId != null) return;
|
|
311
|
+
this.cleanupTimerId = setInterval(() => this.purgeExpired(), this.purgeIntervalMs);
|
|
312
|
+
// プロセス終了をブロックしないよう unref(stdio サーバー / テストの終了を妨げない)
|
|
313
|
+
if (typeof this.cleanupTimerId === 'object' && 'unref' in this.cleanupTimerId) {
|
|
314
|
+
this.cleanupTimerId.unref();
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
/** 定期 purge を停止する(複数回呼んでも安全)。 */
|
|
319
|
+
stopCleanupTimer(): void {
|
|
320
|
+
if (this.cleanupTimerId != null) {
|
|
321
|
+
clearInterval(this.cleanupTimerId);
|
|
322
|
+
this.cleanupTimerId = null;
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
/** 定期 purge タイマーが稼働中かどうか。 */
|
|
327
|
+
isCleanupTimerActive(): boolean {
|
|
328
|
+
return this.cleanupTimerId != null;
|
|
329
|
+
}
|
|
330
|
+
}
|