# ローテーションする OAuth2 リフレッシュトークンを DB 永続化して壊れないようにする型 freee・Google 等の OAuth2 API 連携で「最初は動くのに数時間〜翌日に必ず認証エラーになる」典型バグの回避策。Web アプリ（Next.js/Node 等）に外部会計・SaaS API を繋ぐときの定石。 ## 前提となる落とし穴 多くの OAuth2 プロバイダ（freee 等）は **リフレッシュトークンがローテーションする**＝アクセストークンを更新するたびに新しいリフレッシュトークンが発行され、**古いリフレッシュトークンは即失効**する。 - リフレッシュトークンを環境変数（`REFRESH_TOKEN=...`）に固定で置くと、**1回目の更新後に env の値が無効化され、次回のトークン更新が `invalid_grant` で失敗**する。 - サーバレス（複数インスタンス）では特に、どのインスタンスが更新しても env は書き換わらないので確実に壊れる。 - 症状：「前に渡したトークンが失効していた」「初日は動いたが翌朝から連携エラー」。 ## 解決の型：トークンを DB に持ち、更新のたびに書き戻す 1. **トークン保管テーブルを作る**（単一行）。`client_id` / `client_secret` / `refresh_token` / `access_token` / `access_expires_at` を保持。client_id/secret も同居させると、この API 用の環境変数依存をゼロにできる（秘匿値を env に置けない/CI classifier に止められる環境で有効）。 ```sql create table oauth_tokens ( id text primary key, -- 'default' client_id text not null, client_secret text not null, refresh_token text not null, access_token text, access_expires_at timestamptz, updated_at timestamptz not null default now() ); ``` 2. **`getValidAccessToken()` を1本用意**：期限内ならキャッシュを返す。期限切れならリフレッシュし、**返ってきた新 refresh_token を必ず DB に書き戻す**。 ```ts export async function getValidAccessToken(): Promise { const row = await loadTokenRow(); // DB から1行 if (row.accessToken && row.accessExpiresAt.getTime() > Date.now() + 120_000) { return row.accessToken; // まだ有効 } const res = await fetch(TOKEN_URL, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ grant_type: 'refresh_token', client_id: row.clientId, client_secret: row.clientSecret, refresh_token: row.refreshToken, }), }); if (!res.ok) throw new Error(`token refresh failed (要再認証): ${res.status}`); const j = await res.json(); // { access_token, refresh_token, expires_in } await saveTokenRow({ // ★ 新 refresh_token を必ず永続化 refreshToken: j.refresh_token, accessToken: j.access_token, accessExpiresAt: new Date(Date.now() + j.expires_in * 1000), }); return j.access_token; } ``` 3. **HTTP アダプタはトークンを受け取るだけ**にする（トークン管理を混ぜない）。レイヤ規約（adapters は DB/サービスを import しない）とも整合する。 ```ts export async function apiFetch(path, init, accessToken): Promise { /* Bearer 付与のみ */ } ``` ## 初回接続（トークンの種を入れる） - リフレッシュトークンは **一度だけ OAuth 認可フロー**で取得する（これは人手が要る正規の1操作）。 authorize URL（`redirect_uri=urn:ietf:wg:oauth:2.0:oob` にすると画面にコードが出る CLI 向け）を開く→ログイン＆許可→表示された **認可コード** を1回受領→`grant_type=authorization_code` でトークン交換→DB にシード。 - 以後はローテーションを DB が吸収するので、**再認可は原則不要**（リフレッシュトークン自体の有効期限切れ時のみ再実行）。 ## 実装前に必ずやること：マスタ ID を「取得」する（推測しない） 会計 API 等は勘定科目・税区分・品目などを **ID/コードで指定**する。名前からの推測は事故る。 - 勘定科目：`GET /account_items` を叩き、運用担当（経理）に「この処理はどの科目か」を**実在する科目名の一覧から選んでもらう**。担当が言う名前（例「仕入・原価」）が API 上に存在しないことは普通にある。 - 税区分：`GET /taxes/codes` で**その事業所の実コード**を取得（コードは事業所ごとに異なる）。インボイス経過措置は控除率が枝番（控80%/控50%…）で分かれ、**時期で変わる**点に注意（切替日をコード側に反映する運用を決めておく）。 - 会社/事業所 ID：`GET /companies` で API 用の ID を確定（画面表示の「事業所番号」と API の company_id は別物のことがある）。 ## 二重登録の防止 会計への書き込み（取引登録）は **冪等ガード**必須。 - 「同一案件で成功済みなら再実行を拒否」を DB で判定。 - 非冪等 POST（取引作成）は **失敗時に自動リトライしない**（コミット後の 5xx/タイムアウトで二重登録になる）。リトライは 401（副作用前のトークン失効）だけに限定するか、人手の再送に寄せる。 - 既定は DRY-RUN（実書き込みしないシミュレーション）にし、本番書き込みは管理者権限＋段階導入（テスト1件を実登録して担当が実画面で確認）。 ## チェックリスト - [ ] リフレッシュトークンを env でなく DB に置き、更新のたびに書き戻す - [ ] access_token は期限＋マージンでキャッシュ - [ ] マスタ（勘定科目/税区分/会社ID）は API から取得し、担当に実在名から選定させる - [ ] 取引登録は冪等ガード＋非冪等 POST は無闇にリトライしない - [ ] 既定 DRY-RUN、本番は管理者のみ＋テスト1件で実画面確認 ---