AetherEchoesEngineering
Engineering#022320 min2,474 字8 view

YouTube の refresh_token が 135 日切れない理由は公開ステータス

refresh_token が 7 日で invalid_grant になる条件は、審査の合否ではなく同意画面の公開ステータスだった。同じ token に経過日数の旧判定と実 refresh の新判定を当てると EXPIRED と OK に割れた。切り分け方と preflight の実装を載せる。

SoSoraEndo2026年10月12日 09:0520 min2,474 字

動画で読む

7 日で切れるはずの refresh_token が、135 日たっても切れていない

今朝、動画を YouTube に上げる前に毎回走らせている確認スクリプトを手で叩いた。

$ npx tsx scripts/preflight-youtube.ts; echo exit=$?
token path: ~/.aether-video/youtube-token.json
token age:  135.56 days(参考値・判定には未使用)
OK: refresh_token は有効(access_token 再取得成功、残り約 60 分)
exit=0

135.56 日前に取った refresh_token(アクセストークンを取り直すための長期の鍵)で、今も access_token が取れている。

5 月の時点で、私はこの token が 7 日で死ぬ前提で仕組みを組んでいた。リポジトリの README には今もこう書いてある。

**OAuth verification 承認前(テストモード)は 7 日で refresh_token が失効する**ため、毎週これを実行する。

じゃあ何が変わって、この token は生き延びているのか。そして「何日たったか」で token の健康を測るのはどこが間違っていたのか。手元の token と Google の doc、それにリポジトリの履歴を並べて確かめた。

7 日失効を決めているのは verification の合否ではなく「公開ステータス」だった

最初は「verification(Google によるアプリ審査)が通ったから 7 日制限が外れた」と思っていた。リポジトリの doc もそういう書き方をしている。

ところが Google の OAuth 2.0 の公式ドキュメントを読むと、条件は審査の合否ではなかった。

A Google Cloud Platform project with an OAuth consent screen configured for an external user type and a publishing status of "Testing" is issued a refresh token expiring in 7 days, unless the only OAuth scopes requested are a subset of name, email address, and user profile.

効いているのは publishing status(同意画面の公開ステータス)が Testing かどうか、の一点だ。外部ユーザー向けで、名前・メール・プロフィール以外の scope を要求していて、Testing のまま。この 3 つが揃うと refresh_token に 7 日の寿命が付く。YouTube の youtube.upload や youtube は当然「それ以外の scope」なので、Testing の間は毎週切れていた。

私の場合、2026-05-20 に verification を submit した。そのとき同意画面を Testing から In production に切り替えている。doc の状況欄はこうだ。

> **✅ 2026-05-20 に Submit 完了。Google 審査中(結果待ち、4〜6 週間)**
| Verification ステータス | 審査中 (Branding 公開済 / Data access 検証リクエスト送信済) |
| OAuth consent screen 状態 | In production (Sensitive Scope 含むため verification 必須) |

申請に載せた sensitive scope は youtube.upload / youtube / youtube.readonly の 3 つ。審査結果の見込みは 6 月中旬から 7 月頭だった。

おもしろいのは 6 月 7 日のコミットに残っているコメントで、7 日を超えた token が生きていた理由を「承認されたから」ではなく「本番に公開済みのため」と書いている。

// 【レガシー / 情報表示用】テストモード OAuth では refresh_token が約7日で失効するが、
// 本アプリは OAuth 同意画面を「本番」に公開済みのため、実際には7日を超えても失効しない
// (2026-06-07 に age 8.86 日のトークンで実 API 成功を確認)。

6 月 7 日は審査結果の見込みより前だ。だから 7 日の壁が消えたのは、Testing から外した時点だったと考えている。審査が通ったのはその後だ。承認メールが届いた日付はリポジトリに残っていないので、6 月 7 日にもう承認済みだった可能性は消せない。ただ Google の doc の書き方と合わせると、効いたのは公開ステータスのほうだと思う。

もう一つ、Testing のときに発行された token が、切り替え後にそのまま無期限になるのかは確かめていない。今の token は 5 月 29 日に取り直したもので、切り替えの 9 日後に発行されている。

同じ token を 6 月・7 月・10 月の 3 回見ていた

token ファイルの中身を、値を伏せて見た。

$ jq ... ~/.aether-video/youtube-token.json
{
  "access_token": "<masked 253 chars>",
  "refresh_token": "<masked 103 chars>",
  "scope": "https://www.googleapis.com/auth/youtube.readonly https://www.googleapis.com/auth/youtube",
  "token_type": "Bearer",
  "expiry_date": 1780054493418,
  "expiry_iso": "2026-05-29T11:34:53Z",
  "obtained_at": "2026-05-29T10:34:54.418Z"
}

obtained_at は Google が返す値ではなく、保存するときに自前で足しているタイムスタンプだ。ここから逆算すると、記録に残っている 3 回の観測はどれも同じ token だった。

観測日経過日数出所結果
2026-06-078.86 日youtube-auth.ts のコメント実 API 成功
2026-07-2354 日その日の preflight の出力有効
2026-10-12135.56 日今朝の preflight の出力有効、exit=0

obtained_at の 2026-05-29T10:34

から 6 月 7 日 17
までを計算すると約 8.90 日になる。コメントの 8.86 日は、コミットの少し前に測った値なんだと思う。

ついでに気づいたのが expiry_date で、5 月 29 日 11

のまま止まっている。これは access_token の期限だ。access_token は 1 時間で切れる。preflight は取り直した access_token をファイルに書き戻さないので、ファイル上は 4 か月半前に期限切れの access_token が置きっぱなしになっている。動作には関係ない。ただ、ファイルの expiry_date を見て「切れてる」と判断するスクリプトを書くと、同じ罠にもう一度はまる。

経過日数で判定していた旧 preflight は、この token に「失効」と言う

6 月 7 日より前の preflight は、obtained_at からの経過日数だけで判定していた。7 日以上なら FAIL(exit 2)、6 日台なら WARN(exit 1)。その版を git show で取り出して、今の token に当ててみた。

$ git show bd2c31d^:tools/aether-video/scripts/preflight-youtube.ts > /tmp/aether-oldpf/preflight-old.ts
$ npx tsx /tmp/aether-oldpf/preflight-old.ts; echo exit=$?
token path: ~/.aether-video/youtube-token.json
token age:  135.56 days
remaining:  -128.56 days (lifetime: 7 days)
scope:      https://www.googleapis.com/auth/youtube.readonly https://www.googleapis.com/auth/youtube
EXPIRED: token は 135.6 日経過、refresh_token は失効しているか有効期限を超過しています
対処: cd tools/aether-video && yarn tsx scripts/auth-youtube.ts で再認可
exit=2

同じ token、同じ瞬間で、旧版は EXPIRED で exit 2、新版は OK で exit 0。残り日数は -128.56 days と出ていて、ちょっと笑った。

旧版が間違っていたのは計算ではなく前提だ。「7 日で切れる」は Testing の間だけ正しい外部条件だった。その条件が 5 月 20 日に変わったのに、スクリプトはそれを知る手段を持っていなかった。exit 2 は動画のアップロードを止める合図なので、旧版のままだったら、生きている token を理由に毎回アップロードを止めていたことになる。コミットメッセージの言葉だと「偽の週次再認可ナグ」だ。

新しい判定は「今 refresh できるか」を実際に試すだけ

6 月 7 日に入れた判定の核はこれだけだ。

export const verifyTokenLive = async (): Promise<TokenCheck> => {
  const token = loadToken();
  if (!token || !token.refresh_token) {
    return {ok: false, reason: 'missing', detail: `refresh_token が ${TOKEN_PATH} にありません`};
  }
  const client = buildOAuth2Client('http://localhost:8765/oauth2callback');
  // access_token を渡さず refresh_token のみセット → getAccessToken が必ず再取得を試みる
  client.setCredentials({refresh_token: token.refresh_token});
  try {
    const res = await client.getAccessToken();
    if (!res.token) return {ok: false, reason: 'error', detail: 'access_token を取得できませんでした'};
    const expiry = client.credentials.expiry_date ?? Date.now();
    return {ok: true, expiresInSec: Math.max(0, Math.round((expiry - Date.now()) / 1000))};
  } catch (e) {
    const msg = (e as Error).message || String(e);
    // invalid_grant = refresh_token が本当に失効/失効済み(要再認可)。それ以外は一過性とみなす
    const reason = /invalid_grant/i.test(msg) ? 'invalid_grant' : 'error';
    return {ok: false, reason, detail: msg.slice(0, 160)};
  }
};

ポイントは setCredentials に refresh_token だけを渡しているところ。ファイルの access_token まで渡すと、google-auth-library は期限内ならそれを使い回して終わる。つまり refresh_token を一度も試さない。access_token を渡さなければ、毎回トークンエンドポイントへ取りに行くことになる。

exit code の意味もこれに合わせて変えた。

  • 0: refresh に成功した
  • 1: refresh が invalid_grant 以外のエラーで落ちた(ネットワークなど)。再認可しても直らないので、アップロードは試させる
  • 2: token が無い、または invalid_grant。人がブラウザで再認可するしかない

invalid_grant がどんな形で返るのか、存在しない refresh_token を渡して見てみた。

$ npx tsx /tmp/aether-oldpf/bogus.ts
message: invalid_grant
status: 400
data: {"error":"invalid_grant","error_description":"Bad Request"}

HTTP 400 で、error に invalid_grant が入る。error.message にも同じ文字列が来るので、正規表現 1 本で拾える。ただ、これは「存在しない token」の場合の形だ。Testing の 7 日で本当に失効した token が同じ error_description を返すかは、もう Testing に戻せないので確かめていない。

refresh で取れた access_token を tokeninfo に見せると、寿命は 1 時間だった

最後に、refresh で取り直した access_token を Google の tokeninfo エンドポイントに投げた(値はマスク)。

$ curl -s "https://oauth2.googleapis.com/tokeninfo?access_token=<masked>"
{
  "azp": "980674…<masked>",
  "aud": "980674…<masked>",
  "scope": "https://www.googleapis.com/auth/youtube https://www.googleapis.com/auth/youtube.readonly",
  "exp": "1791766911",
  "expires_in": "3598",
  "access_type": "offline",
  "sub": null
}

expires_in は 3598 秒。発行からほぼ 1 時間で、preflight の「残り約 60 分」と一致する。access_type: offline は、認可のときに access_type: 'offline' と prompt: 'consent' を付けて refresh_token をもらっているからだ。

2 種類の token の寿命はまるで違う。

寿命何で決まるか
access_token3,600 秒固定。tokeninfo の expires_in で見える
refresh_token(Testing)7 日同意画面の公開ステータス
refresh_token(In production)決まった期限なし取り消し・6 か月未使用・発行数上限などのイベントで死ぬ

最後の行は Google の doc に並んでいる失効理由だ。ユーザーによる取り消し、6 か月使われない、Gmail scope を含む場合のパスワード変更、1 アカウント × 1 クライアント ID あたり 100 本の上限を超えて古いものから消される、など。どれも「何日たったか」では予測できない。だから日数ではなく実際の refresh で見るしかない。

「6 か月未使用」については、preflight が refresh するたびに token は「使われた」ことになるはずだ。毎週動画を上げている限り、この理由で死ぬことはたぶん無い。そこまでは検証していない。

自分の環境で切り分けるなら、見るのは 3 か所

invalid_grant が出て「7 日の罠か?」と思ったら、私なら次の順で見る。

  1. Google Cloud Console の Audience 画面で、publishing status が Testing か In production か。Testing で、scope が名前・メール・プロフィールの外にあるなら、7 日失効がまず疑わしい
  2. token を取った日時。自前で obtained_at を残していなければ、発行日は後から分からない。残しておくと、7 日ちょうどで死んだのかどうかを判定できる
  3. 失効の判定を、日数ではなく getAccessToken() の成否でやっているか。access_token をセットしたまま呼ぶと refresh_token を試さずに成功してしまうので、refresh_token だけをセットする

この token は今日も 1 時間ぶんの access_token をもらった。README の「毎週これを実行する」の行と、経過日数の閾値の表は、まだ 5 月の前提のまま残っている。次に直すのはそこだ。

Tags

参考文献

  1. Using OAuth 2.0 to Access Google APIs: Refresh token expiration(Google for Developers)
  2. OAuth 2.0 for Mobile & Desktop Apps(YouTube Data API)
  3. google-auth-library-nodejs(OAuth2Client.getAccessToken)

Reaction

Share

X (Twitter)