diff --git a/docs/decisions.md b/docs/decisions.md index 1f8ad45..04d2863 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -1446,7 +1446,8 @@ behind it, and what a reviewer should check. IDs are stable; append, do not renu before any flow starts, so nobody approves a login that cannot be kept. - The refresh window grows from 60 seconds to 30 minutes, so every command starts with at least that long left and a long `wait` does not outlive its - token. A refresh also keeps the profile's `region` (it used to drop it, + token. (D-095 narrows it to two thirds of the lifetime for a token that lives + less than 45 minutes.) A refresh also keeps the profile's `region` (it used to drop it, moving a China-site login to the global site an hour after sign-in) and `account`. - DeepSeek Harness lets a plugin add only `DSH_*` variables to a shell call, and @@ -1720,3 +1721,25 @@ behind it, and what a reviewer should check. IDs are stable; append, do not renu `--no-open` skips the default browser (`MESHY_CLI_NO_BROWSER` does as well). - Reviewer check: a new route must not widen what the server reads beyond the one model and its own referenced files. + +## D-095 The refresh window follows the token's lifetime + +- D-088's 30-minute window assumed an access token that lives longer than 30 + minutes. The API now also issues access tokens that live 15 minutes + (`expires_in: 900`). Such a token is always inside a 30-minute window, so + every command refreshed it before running, and a quick run of commands (an + agent working through a batch) hit the token endpoint's per-address limit + with HTTP 429. +- The window is now 30 minutes or two thirds of the token's lifetime, + whichever is shorter (`refreshSkewMs`). A 15-minute token is refreshed with + 10 minutes left, still enough for the default 10-minute `wait`; a token that + lives 45 minutes or more keeps the 30-minute window, so nothing changes for + it. +- The lifetime is `expires_at - issued_at`. Logins and refreshes now record + `issued_at` in the profile. A profile saved by an older CLI has none and keeps + the 30-minute window until its next refresh records one; an older CLI that + refreshes the profile drops it again, which only costs one extra refresh. +- A `wait` longer than the token's remaining life still ends on its 401, as + before; refreshing during a wait is separate work. +- Reviewer check: a change to the window must keep a fresh token outside it, + or every command refreshes again. diff --git a/docs/usage.md b/docs/usage.md index 99b43a9..d81d87e 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -73,11 +73,13 @@ first write, which moves the profiles into the encrypted file and deletes it. An older CLI on the same machine then finds no login and signs in once on its own; the two logins do not interfere afterwards. -**OAuth token refresh:** when the stored OAuth access token is within 30 minutes -of expiry (or already expired), the CLI silently refreshes it using the stored -refresh token before running the command, so a command never starts with a -token about to run out. A refresh failure with an unexpired token is swallowed -(the existing token is used); a failure with an expired token exits `3` with a +**OAuth token refresh:** when the stored OAuth access token has less than 30 +minutes left (for a token that lives less than 45 minutes: less than two thirds +of its lifetime, so 10 minutes for a 15-minute token), or has already expired, +the CLI silently refreshes it using the stored refresh token before running the +command, so a command never starts with a token about to run out. A refresh +failure with an unexpired token is swallowed (the existing token is used); a +failure with an expired token exits `3` with a hint to run `meshy auth login`. Where the credentials directory cannot be written — a sandboxed agent shell — the CLI does not refresh at all: the API replaces the refresh token on every use, so a refresh it could not save would diff --git a/src/cmd/auth.ts b/src/cmd/auth.ts index 78a95ec..bbfe522 100644 --- a/src/cmd/auth.ts +++ b/src/cmd/auth.ts @@ -146,6 +146,7 @@ async function finishLogin( ): Promise { const file = resolveFile(flags); const account = await fetchAccount(baseUrlV1, tok.access_token); + const issuedAt = Date.now(); // Every login gets its own identifier: the operation journal binds a // submission to the account (user_id) when the token endpoint reports one, // and to this login otherwise — never to a token that rotates on refresh. @@ -153,7 +154,8 @@ async function finishLogin( kind: "oauth" as const, access_token: tok.access_token, refresh_token: tok.refresh_token, - expires_at: Date.now() + tok.expires_in * 1000, + expires_at: issuedAt + tok.expires_in * 1000, + issued_at: issuedAt, ...(tok.user_id ? { user_id: tok.user_id } : {}), login_id: randomUUID(), ...(regionOf(baseUrlV1) ? { region: "cn" as const } : {}), diff --git a/src/internal/credentials.ts b/src/internal/credentials.ts index b369b57..7c4cb40 100644 --- a/src/internal/credentials.ts +++ b/src/internal/credentials.ts @@ -83,6 +83,12 @@ export interface CredentialProfile { account?: CredentialAccount; /** Unix epoch millis. */ expires_at?: number; + /** + * Unix epoch millis when the access token was received, so expires_at - + * issued_at is its lifetime (refreshSkewMs). Absent on a profile an older + * CLI saved. + */ + issued_at?: number; user_id?: string; /** * Random identifier minted by `meshy auth login` for OAuth profiles. It diff --git a/src/internal/runtime.ts b/src/internal/runtime.ts index 6d8e1d6..759d3bc 100644 --- a/src/internal/runtime.ts +++ b/src/internal/runtime.ts @@ -57,13 +57,31 @@ export interface LocalRuntime { } /** - * Refresh an OAuth credential this far ahead of expiry. Every command then - * starts with at least this long left, so a long `wait` does not outlive its - * token, and a host app that re-reads the token on a schedule shorter than - * this always hands out one with time to spare. + * Refresh an OAuth credential this far ahead of expiry, or sooner for a token + * that lives less than 45 minutes (refreshSkewMs). Every command then starts + * with at least this long left, or two thirds of a shorter-lived token's + * lifetime, so a long `wait` does not outlive its token, and a host app that + * re-reads the token on a schedule shorter than that always hands out one + * with time to spare. */ export const REFRESH_SKEW_MS = 30 * 60_000; +/** + * How far ahead of expiry to refresh this profile's token: REFRESH_SKEW_MS, + * or two thirds of the token's lifetime when that is shorter. A token that + * lives less than REFRESH_SKEW_MS would otherwise be refreshed by every + * command, since it is always within the window: a 15-minute token is + * refreshed with 10 minutes left instead, still enough for the default + * 10-minute `wait`. The lifetime is expires_at - issued_at; a profile saved + * without issued_at keeps REFRESH_SKEW_MS until its next refresh records it. + */ +export function refreshSkewMs(profile: { expires_at?: number; issued_at?: number } | undefined): number { + const expiresAt = profile?.expires_at; + const issuedAt = profile?.issued_at; + if (!expiresAt || !issuedAt || expiresAt <= issuedAt) return REFRESH_SKEW_MS; + return Math.min(REFRESH_SKEW_MS, Math.floor(((expiresAt - issuedAt) * 2) / 3)); +} + /** * Silently refresh an OAuth credential when it is near expiry or already * expired, then return the config to use (refreshed+reloaded, or original). @@ -71,7 +89,7 @@ export const REFRESH_SKEW_MS = 30 * 60_000; * No-ops unless: * - credentialSource === "file" * - the active profile is kind "oauth" with a refresh_token - * - the access_token expires within REFRESH_SKEW_MS (or is already past) + * - the access_token expires within refreshSkewMs(profile) (or is already past) * * When the store cannot be written here (a sandboxed agent shell), the * refresh is skipped: the API rotates the refresh token on use, so a refresh @@ -106,7 +124,7 @@ export async function refreshOAuthCredentialIfNeeded( if (!profile || profile.kind !== "oauth") return config; const expiresAt = profile.expires_at ?? 0; - const needsRefresh = expiresAt - Date.now() < REFRESH_SKEW_MS; + const needsRefresh = expiresAt - Date.now() < refreshSkewMs(profile); if (!needsRefresh) return config; const secrets = profileSecrets(credFile, profile); @@ -134,17 +152,19 @@ export async function refreshOAuthCredentialIfNeeded( try { const current = readCredentials(credFile)?.profiles[profileName]; const refreshToken = current?.kind === "oauth" ? profileSecrets(credFile, current).refresh_token : undefined; - if (current && (current.expires_at ?? 0) - Date.now() >= REFRESH_SKEW_MS) { + if (current && (current.expires_at ?? 0) - Date.now() >= refreshSkewMs(current)) { logger.debug("OAuth token already refreshed by another process"); } else if (current && refreshToken) await withExitHeld(async () => { const tok = await refreshTokens({ baseUrlV1: config.baseUrlV1, refreshToken }); + const issuedAt = Date.now(); // Write back: preserve profile name, created_at, region and account. updateCredentialsHeld(credFile, (state) => { state.profiles[profileName] = { kind: "oauth", access_token: tok.access_token, refresh_token: tok.refresh_token, - expires_at: Date.now() + tok.expires_in * 1000, + expires_at: issuedAt + tok.expires_in * 1000, + issued_at: issuedAt, user_id: tok.user_id ?? current.user_id, ...(current.login_id ? { login_id: current.login_id } : {}), ...(current.region ? { region: current.region } : {}), @@ -157,7 +177,7 @@ export async function refreshOAuthCredentialIfNeeded( // B3: Read-after-write — a CLI before 0.8.1 refreshes outside the lock // and may already have rotated the token (server-side refresh-token // rotation). Re-read the file; if the active profile now holds a - // DIFFERENT access token that is comfortably unexpired (>REFRESH_SKEW_MS), + // DIFFERENT access token that is comfortably unexpired (>refreshSkewMs), // adopt it and proceed rather than failing the command. const afterFailure = readCredentials(credFile); const afterProfile = profileName ? afterFailure?.profiles[profileName] : undefined; @@ -165,7 +185,7 @@ export async function refreshOAuthCredentialIfNeeded( if ( afterToken && afterToken !== originalAccessToken && - (afterProfile?.expires_at ?? 0) - Date.now() > REFRESH_SKEW_MS + (afterProfile?.expires_at ?? 0) - Date.now() > refreshSkewMs(afterProfile) ) { // Another process already rotated — adopt the new token. logger.debug("OAuth refresh failed but concurrent rotation detected; adopting new token"); @@ -201,7 +221,7 @@ export function configOverridesFrom(flags: GlobalFlags): ConfigOverrides { * Build the authenticated runtime for this invocation. * * When the active credential is an OAuth profile with a refresh_token and the - * access_token is within REFRESH_SKEW_MS of expiry (or already expired), this + * access_token is within refreshSkewMs(profile) of expiry (or already expired), this * silently refreshes the token, writes the new tokens back to the credentials * file, and re-runs loadConfig so the client carries the fresh token. * diff --git a/tests/refresh-skew.test.ts b/tests/refresh-skew.test.ts new file mode 100644 index 0000000..5f71f0e --- /dev/null +++ b/tests/refresh-skew.test.ts @@ -0,0 +1,32 @@ +/** + * refreshSkewMs: how far ahead of expiry a stored OAuth token is refreshed. + * A token shorter-lived than the 30-minute window must not be refreshed by + * every command, and a long-lived one keeps the window it always had. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { REFRESH_SKEW_MS, refreshSkewMs } from "../src/internal/runtime.js"; + +const minute = 60_000; +const now = 1_800_000_000_000; + +test("a 15-minute token refreshes with 10 minutes left", () => { + assert.equal(refreshSkewMs({ issued_at: now, expires_at: now + 15 * minute }), 10 * minute); +}); + +test("a 60-minute token keeps the 30-minute window", () => { + assert.equal(REFRESH_SKEW_MS, 30 * minute); + assert.equal(refreshSkewMs({ issued_at: now, expires_at: now + 60 * minute }), 30 * minute); +}); + +test("a 45-minute token keeps the 30-minute window (two thirds is exactly 30)", () => { + assert.equal(refreshSkewMs({ issued_at: now, expires_at: now + 45 * minute }), 30 * minute); +}); + +test("a profile without issued_at, or with a nonsensical one, keeps the 30-minute window", () => { + assert.equal(refreshSkewMs({ expires_at: now + 15 * minute }), 30 * minute); + assert.equal(refreshSkewMs({ issued_at: now, expires_at: now }), 30 * minute); + assert.equal(refreshSkewMs({ issued_at: now + minute, expires_at: now }), 30 * minute); + assert.equal(refreshSkewMs(undefined), 30 * minute); +}); diff --git a/tests/runtime.test.ts b/tests/runtime.test.ts index d36395c..ec8d11c 100644 --- a/tests/runtime.test.ts +++ b/tests/runtime.test.ts @@ -67,6 +67,7 @@ function writeOauthCreds( accessToken: string; refreshToken: string; expiresAt: number; + issuedAt?: number; userId?: string; }, ): void { @@ -82,6 +83,7 @@ function writeOauthCreds( access_token: opts.accessToken, refresh_token: opts.refreshToken, expires_at: opts.expiresAt, + ...(opts.issuedAt ? { issued_at: opts.issuedAt } : {}), ...(opts.userId ? { user_id: opts.userId } : {}), created_at: Date.now() - 1000, }, @@ -604,3 +606,113 @@ test( } }, ); + +// --------------------------------------------------------------------------- +// The refresh window follows the token's lifetime (refreshSkewMs): a token +// that lives less than 30 minutes is not refreshed by every command. +// --------------------------------------------------------------------------- + +/** A token endpoint that counts its calls and answers a 15-minute token. */ +async function startCountingTokenStub(): Promise<{ url: string; close: () => Promise; calls: () => number }> { + let calls = 0; + const stub = await startStub((req: IncomingMessage, res: ServerResponse) => { + const url = new URL(req.url ?? "/", "http://localhost"); + if (url.pathname === "/oauth/token") { + calls++; + req.resume(); + req.on("end", () => { + res.writeHead(200, { "Content-Type": "application/json" }); + res.end(JSON.stringify({ + access_token: `refreshed-token-${calls}`, + token_type: "Bearer", + expires_in: 900, + refresh_token: `refreshed-refresh-${calls}`, + })); + }); + return; + } + res.writeHead(404); + res.end("not found"); + }); + return { ...stub, calls: () => calls }; +} + +test( + "a 15-minute token with 13 minutes left is used as it is, not refreshed", + { timeout: 15_000 }, + async () => { + const dir = makeTmpDir(); + const credFile = join(dir, "credentials.json"); + const issuedAt = Date.now() - 2 * 60_000; + writeOauthCreds(credFile, { + accessToken: "short-lived-token", + refreshToken: "short-lived-refresh", + issuedAt, + expiresAt: issuedAt + 15 * 60_000, + }); + const stub = await startCountingTokenStub(); + try { + const result = await runBuildRuntime({ credFile, baseUrlV1: stub.url, expectSuccess: true }); + const parsed = JSON.parse(result.stdout.trim()) as { ok: boolean; apiKey?: string; message?: string }; + assert.equal(parsed.ok, true, `expected success, got: ${parsed.message}\nstderr: ${result.stderr}`); + assert.equal(parsed.apiKey, "short-lived-token", "the stored token is used"); + assert.equal(stub.calls(), 0, "no refresh: 13 minutes left is outside the 10-minute window of a 15-minute token"); + } finally { + await stub.close(); + } + }, +); + +test( + "a 15-minute token with 9 minutes left is refreshed, and the new token's lifetime is recorded", + { timeout: 15_000 }, + async () => { + const dir = makeTmpDir(); + const credFile = join(dir, "credentials.json"); + const issuedAt = Date.now() - 6 * 60_000; + writeOauthCreds(credFile, { + accessToken: "short-lived-token", + refreshToken: "short-lived-refresh", + issuedAt, + expiresAt: issuedAt + 15 * 60_000, + }); + const stub = await startCountingTokenStub(); + try { + const before = Date.now(); + const result = await runBuildRuntime({ credFile, baseUrlV1: stub.url, expectSuccess: true }); + const parsed = JSON.parse(result.stdout.trim()) as { ok: boolean; apiKey?: string; message?: string }; + assert.equal(parsed.ok, true, `expected success, got: ${parsed.message}\nstderr: ${result.stderr}`); + assert.equal(stub.calls(), 1, "one refresh"); + assert.equal(parsed.apiKey, "refreshed-token-1"); + const profile = openStoredProfile(credFile) as { issued_at?: number; expires_at?: number }; + assert.ok(profile.issued_at !== undefined && profile.issued_at >= before, `issued_at recorded, got ${profile.issued_at}`); + assert.equal((profile.expires_at ?? 0) - (profile.issued_at ?? 0), 900_000, "expires_at - issued_at is the 900 s lifetime"); + } finally { + await stub.close(); + } + }, +); + +test( + "a profile saved without issued_at keeps the 30-minute window: 20 minutes left is refreshed", + { timeout: 15_000 }, + async () => { + const dir = makeTmpDir(); + const credFile = join(dir, "credentials.json"); + writeOauthCreds(credFile, { + accessToken: "legacy-token", + refreshToken: "legacy-refresh", + expiresAt: Date.now() + 20 * 60_000, + }); + const stub = await startCountingTokenStub(); + try { + const result = await runBuildRuntime({ credFile, baseUrlV1: stub.url, expectSuccess: true }); + const parsed = JSON.parse(result.stdout.trim()) as { ok: boolean; apiKey?: string; message?: string }; + assert.equal(parsed.ok, true, `expected success, got: ${parsed.message}\nstderr: ${result.stderr}`); + assert.equal(stub.calls(), 1, "refreshed under the 30-minute window"); + assert.equal(parsed.apiKey, "refreshed-token-1"); + } finally { + await stub.close(); + } + }, +);