Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
12 changes: 7 additions & 5 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion src/cmd/auth.ts
Original file line number Diff line number Diff line change
Expand Up @@ -146,14 +146,16 @@ async function finishLogin(
): Promise<void> {
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.
const profileData = {
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 } : {}),
Expand Down
6 changes: 6 additions & 0 deletions src/internal/credentials.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
42 changes: 31 additions & 11 deletions src/internal/runtime.ts
Original file line number Diff line number Diff line change
Expand Up @@ -57,21 +57,39 @@ 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).
*
* 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
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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 } : {}),
Expand All @@ -157,15 +177,15 @@ 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;
const afterToken = afterProfile?.kind === "oauth" ? profileSecrets(credFile, afterProfile).access_token : undefined;
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");
Expand Down Expand Up @@ -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.
*
Expand Down
32 changes: 32 additions & 0 deletions tests/refresh-skew.test.ts
Original file line number Diff line number Diff line change
@@ -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);
});
112 changes: 112 additions & 0 deletions tests/runtime.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@ function writeOauthCreds(
accessToken: string;
refreshToken: string;
expiresAt: number;
issuedAt?: number;
userId?: string;
},
): void {
Expand All @@ -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,
},
Expand Down Expand Up @@ -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<void>; 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();
}
},
);
Loading