@mulmoclaude/core 0.21.0 → 0.22.0

package/assets/helps/error-recovery.md

@@ -304,31 +304,41 @@ shipped builders produce, and asserts `handlePermission` comes back over the MCP
 ### Symptoms
 
 - The `google` tool (or a `google.calendar.*` remote command) fails with **"Google account not linked on this host"**.
-- Errors mentioning **client_secret**: "no client_secret_*.json found" or "multiple client_secret_*.json files found".
+- **"Google sign-in service unreachable"** or **"Google sign-in service returned HTTP …"**.
+- **"multiple client_secret_*.json files found"**.
 - **"Google Calendar API: HTTP 403"** with a hint about enabling the API.
 - **"could not obtain a Google access token"** (grant revoked).
 
 ### Cause
 
 The `google` tool runs against a Google account linked **locally on this machine** — a refresh
-token stored at `~/.config/mulmo/google-token.json` (mode 600), obtained through a desktop
-OAuth (loopback + PKCE) consent using the client credentials in `~/.secrets/client_secret_*.json`.
-This is independent of claude.ai Google connectors. Each failure names its missing piece.
+token stored at `~/.config/mulmo/google-token.json` (mode 600), obtained through a browser
+consent (loopback + PKCE). This is independent of claude.ai Google connectors.
+
+Two ways the link can be minted, and the tool picks automatically:
+
+- **Default**: the user just clicks link and consents. The mulmoserver broker applies the OAuth
+  client secret for the token exchange / renewal (Google requires one); it stores nothing —
+  the tokens live only on this machine. **The user needs no Google Cloud setup.**
+- **Own client** (advanced / self-hosters): if `~/.secrets/client_secret_*.json` exists, the
+  whole flow stays on this machine and the broker is never contacted.
 
 ### Fix
 
-- **Not linked / grant revoked** — ask the user to link (or re-link) the account: Settings →
-  Plugins → Google → "Link Google account", or run `yarn google:auth` in the repo. Then retry the
-  original call. Do NOT try to create or edit the token file yourself.
-- **No client secret** — the user must download the OAuth *desktop-app* client JSON from the
-  Google Cloud Console (APIs & Services → Credentials) and place it in `~/.secrets/` keeping the
-  `client_secret_*.json` filename (chmod 600).
-- **Multiple client secrets** — ask the user to keep exactly one `client_secret_*.json` in
-  `~/.secrets/`; the stored refresh token pairs with one OAuth client, so duplicates are refused
-  rather than guessed at.
-- **HTTP 403 from a Google API** — the API is not enabled for the user's Cloud project. The error
-  names the API; ask them to enable that one in the Cloud Console (APIs & Services → Library —
-  "Google Calendar API", "Google Tasks API", or "Google Drive API"), then retry. No re-link needed.
+- **Not linked / grant revoked** — ask the user to link (or re-link) the account from this app's
+  settings, then retry. Do NOT tell them to create a Google Cloud project, and do NOT try to
+  create or edit the token file yourself.
+- **Sign-in service unreachable / HTTP error** — the broker is down or the network is blocked.
+  It is only needed to link and to renew an expired access token; ask the user to retry shortly.
+  (A user with their own `~/.secrets/client_secret_*.json` never depends on it.)
+- **Multiple client secrets** — the user has several `client_secret_*.json` in `~/.secrets/`;
+  a stored refresh token pairs with exactly one OAuth client, so the choice is refused rather
+  than guessed at. Ask them to keep one — or remove all of them to use the default flow.
+- **HTTP 403 from a Google API** — the API is not enabled for the Cloud project behind the
+  client in use. With their own client, ask them to enable that API in the Cloud Console
+  (APIs & Services → Library — the error names it: "Google Calendar API", "Google Tasks API",
+  or "Google Drive API"), then retry — no re-link needed. On the default (broker) flow this
+  should not happen; report it rather than sending the user to the Console.
 - **Drive shows nothing / "I can't find the user's file"** — not an error. The app holds the
   `drive.file` scope, so it can only ever see files IT created; the user's wider Drive is
   invisible by design. Say so plainly instead of implying an empty Drive.

package/dist/google/broker.d.ts

@@ -0,0 +1,15 @@
+import { Credentials } from 'google-auth-library';
+/** `MULMO_GOOGLE_BROKER_URL` lets a fork / staging deploy point elsewhere
+ *  without a code change; unset means the shipped broker. */
+export declare const brokerBaseUrl: (override?: string | undefined) => string;
+export interface BrokerStartResponse {
+    authUrl: string;
+    state: string;
+}
+export declare function brokerStart(port: number, codeChallenge: string, baseUrl?: string): Promise<BrokerStartResponse>;
+export declare function brokerExchange(input: {
+    code: string;
+    state: string;
+    codeVerifier: string;
+}, baseUrl?: string): Promise<Credentials>;
+export declare function brokerRefresh(refreshToken: string, baseUrl?: string): Promise<Credentials>;

package/dist/google/clientSecret.d.ts

@@ -2,9 +2,10 @@ export interface InstalledClientSecret {
     client_id: string;
     client_secret: string;
 }
-/** "ambiguous" (2+ files) is distinct from "missing" — the fixes differ
- *  (remove duplicates vs download credentials), so the UI must not conflate
- *  them. */
+/** `missing` is the ordinary case — the broker supplies the client, so no user
+ *  action is needed. `ambiguous` (2+ desktop clients) still needs a human:
+ *  a stored refresh token pairs with exactly one client_id, so picking for
+ *  them could silently break the link. */
 export type ClientSecretPresence = "found" | "missing" | "ambiguous";
 export declare function clientSecretPresence(home?: string): Promise<ClientSecretPresence>;
 export declare function findClientSecretPath(home?: string): Promise<string>;

package/dist/google/index.cjs

@@ -80,31 +80,44 @@ function truncate(text, max, ellipsis = "…") {
 }
 //#endregion
 //#region src/google/clientSecret.ts
+var isNonEmptyString = (value) => typeof value === "string" && value !== "";
 var isInstalledClientSecret = (value) => {
 	if (!isRecord(value) || !isRecord(value.installed)) return false;
-	return typeof value.installed.client_id === "string" && typeof value.installed.client_secret === "string";
+	return isNonEmptyString(value.installed.client_id) && isNonEmptyString(value.installed.client_secret);
 };
 var isClientSecretFileName = (name) => name.startsWith("client_secret_") && name.endsWith(".json");
-async function listClientSecretFiles(home) {
-	return (await (0, node_fs_promises.readdir)(googleSecretsDir(home)).catch(() => [])).filter(isClientSecretFileName).sort();
+var readIfDesktopClient = async (filePath) => {
+	try {
+		return isInstalledClientSecret(JSON.parse(await (0, node_fs_promises.readFile)(filePath, "utf-8"))) ? filePath : null;
+	} catch {
+		return null;
+	}
+};
+/** Absolute paths of every desktop-app client JSON in `~/.secrets/`. */
+async function listDesktopClientSecretFiles(home) {
+	const dir = googleSecretsDir(home);
+	const candidates = (await (0, node_fs_promises.readdir)(dir).catch(() => [])).filter(isClientSecretFileName).sort();
+	return (await Promise.all(candidates.map((name) => readIfDesktopClient((0, node_path.join)(dir, name))))).filter((path) => path !== null);
 }
 async function clientSecretPresence(home) {
-	const matches = await listClientSecretFiles(home);
+	const matches = await listDesktopClientSecretFiles(home);
 	if (matches.length === 0) return "missing";
 	return matches.length === 1 ? "found" : "ambiguous";
 }
 async function findClientSecretPath(home) {
 	const dir = googleSecretsDir(home);
-	const matches = await listClientSecretFiles(home);
+	const matches = await listDesktopClientSecretFiles(home);
 	const [first, ...rest] = matches;
-	if (!first) throw new Error(`no client_secret_*.json found in ${dir} — download the OAuth desktop-app credentials JSON from the Google Cloud Console and place it there (mode 600)`);
-	if (rest.length > 0) throw new Error(`multiple client_secret_*.json files found in ${dir} (${matches.join(", ")}) — keep exactly one`);
-	return (0, node_path.join)(dir, first);
+	if (!first) throw new Error(`no desktop-app client_secret_*.json found in ${dir} — this host links through the sign-in service instead`);
+	if (rest.length > 0) {
+		const names = matches.map((path) => path.slice(dir.length + 1)).join(", ");
+		throw new Error(`multiple desktop-app client_secret_*.json files found in ${dir} (${names}) — keep exactly one`);
+	}
+	return first;
 }
 async function loadClientSecret(home) {
 	const filePath = await findClientSecretPath(home);
-	const raw = await (0, node_fs_promises.readFile)(filePath, "utf-8");
-	const parsed = JSON.parse(raw);
+	const parsed = JSON.parse(await (0, node_fs_promises.readFile)(filePath, "utf-8"));
 	if (!isInstalledClientSecret(parsed)) throw new Error(`${filePath} is not a desktop-app OAuth client secret (missing "installed" with client_id / client_secret)`);
 	return {
 		client_id: parsed.installed.client_id,
@@ -164,6 +177,7 @@ function mergeGoogleTokens(existing, incoming) {
 		...incoming
 	};
 	if (!incoming.refresh_token && existing?.refresh_token) merged.refresh_token = existing.refresh_token;
+	if (!incoming.issuedVia && existing?.issuedVia) merged.issuedVia = existing.issuedVia;
 	return merged;
 }
 var fileExists = async (filePath) => await (0, node_fs_promises.stat)(filePath).then(() => true, () => false);
@@ -224,6 +238,113 @@ function bridgeExternalSignal(external, controller) {
 	return () => external.removeEventListener("abort", onAbort);
 }
 //#endregion
+//#region src/google/broker.ts
+var DEFAULT_BROKER_BASE_URL = "https://asia-northeast1-mulmoserver.cloudfunctions.net";
+var BROKER_TIMEOUT_MS = 20 * ONE_SECOND_MS;
+var withoutTrailingSlashes = (url) => {
+	let end = url.length;
+	while (end > 0 && url[end - 1] === "/") end -= 1;
+	return url.slice(0, end);
+};
+/** `MULMO_GOOGLE_BROKER_URL` lets a fork / staging deploy point elsewhere
+*  without a code change; unset means the shipped broker. */
+var brokerBaseUrl = (override = process.env.MULMO_GOOGLE_BROKER_URL) => withoutTrailingSlashes(override ?? DEFAULT_BROKER_BASE_URL);
+var LOOPBACK_HOSTNAMES = /* @__PURE__ */ new Set([
+	"127.0.0.1",
+	"localhost",
+	"::1",
+	"[::1]"
+]);
+/** Codes, PKCE verifiers and refresh tokens travel to the broker, so cleartext
+*  is refused outright — an override pointed at `http://…` would put them on
+*  the wire. Loopback stays allowed: that is where tests stub the broker, and
+*  it never leaves the machine. */
+var assertSecureBrokerUrl = (url) => {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new Error(`invalid Google sign-in service URL: ${url}`);
+	}
+	if (parsed.protocol === "https:") return;
+	if (parsed.protocol === "http:" && LOOPBACK_HOSTNAMES.has(parsed.hostname)) return;
+	throw new Error(`the Google sign-in service must be reached over HTTPS (got ${parsed.protocol}//${parsed.host})`);
+};
+var brokerFetch = async (url, init = {}) => {
+	assertSecureBrokerUrl(url);
+	let response;
+	try {
+		response = await fetchWithTimeout(url, {
+			...init,
+			timeoutMs: BROKER_TIMEOUT_MS,
+			headers: { "Content-Type": "application/json" }
+		});
+	} catch (err) {
+		throw new Error(`Google sign-in service unreachable — check the network connection and retry (${errorMessage(err)})`);
+	}
+	if (!response.ok) throw new Error(`Google sign-in service returned HTTP ${response.status}`);
+	try {
+		return await response.json();
+	} catch {
+		throw new Error("Google sign-in service returned a malformed response");
+	}
+};
+var GOOGLE_CONSENT_HOST = "accounts.google.com";
+/** The returned URL is opened in the user's browser, so it must be Google's
+*  own consent page and nothing else — a mis-pointed or hostile broker (the
+*  base URL is overridable) could otherwise hand back a phishing page wearing
+*  a sign-in flow. Cheap to assert, and Google's endpoint host is fixed. */
+var assertGoogleConsentUrl = (authUrl) => {
+	let parsed;
+	try {
+		parsed = new URL(authUrl);
+	} catch {
+		throw new Error("Google sign-in service returned an unusable authorization URL");
+	}
+	if (parsed.protocol !== "https:" || parsed.hostname !== GOOGLE_CONSENT_HOST) throw new Error(`Google sign-in service returned an authorization URL that is not Google's consent page (${parsed.protocol}//${parsed.host})`);
+};
+async function brokerStart(port, codeChallenge, baseUrl = brokerBaseUrl()) {
+	const payload = await brokerFetch(`${baseUrl}/googleOAuthStart?${new URLSearchParams({
+		port: String(port),
+		code_challenge: codeChallenge
+	}).toString()}`);
+	const record = isRecord(payload) ? payload : {};
+	if (typeof record.auth_url !== "string" || typeof record.state !== "string") throw new Error("Google sign-in service returned an unexpected response (missing auth_url / state)");
+	assertGoogleConsentUrl(record.auth_url);
+	return {
+		authUrl: record.auth_url,
+		state: record.state
+	};
+}
+var toCredentials = (payload, existingRefreshToken) => {
+	const record = isRecord(payload) ? payload : {};
+	if (typeof record.access_token !== "string") throw new Error("Google sign-in service returned no access token");
+	const refreshToken = typeof record.refresh_token === "string" ? record.refresh_token : existingRefreshToken;
+	return {
+		access_token: record.access_token,
+		...refreshToken ? { refresh_token: refreshToken } : {},
+		...typeof record.expiry_date === "number" ? { expiry_date: record.expiry_date } : {}
+	};
+};
+async function brokerExchange(input, baseUrl = brokerBaseUrl()) {
+	const credentials = toCredentials(await brokerFetch(`${baseUrl}/googleOAuthExchange`, {
+		method: "POST",
+		body: JSON.stringify({
+			code: input.code,
+			state: input.state,
+			code_verifier: input.codeVerifier
+		})
+	}));
+	if (!credentials.refresh_token) throw new Error("Google returned no refresh token — remove this app under Google Account → Security → Third-party access, then retry");
+	return credentials;
+}
+async function brokerRefresh(refreshToken, baseUrl = brokerBaseUrl()) {
+	return toCredentials(await brokerFetch(`${baseUrl}/googleOAuthRefresh`, {
+		method: "POST",
+		body: JSON.stringify({ refresh_token: refreshToken })
+	}), refreshToken);
+}
+//#endregion
 //#region src/google/auth.ts
 var GOOGLE_CALENDAR_SCOPE = "https://www.googleapis.com/auth/calendar.events";
 var GOOGLE_TASKS_SCOPE = "https://www.googleapis.com/auth/tasks";
@@ -239,6 +360,9 @@ var GOOGLE_SCOPES = [
 var CALLBACK_PATH = "/oauth2callback";
 var AUTH_TIMEOUT_MS = 5 * ONE_MINUTE_MS;
 var STATE_BYTES = 16;
+/** Renew a minute early so a call can't start with a token that expires
+*  mid-flight. */
+var EXPIRY_MARGIN_MS = ONE_MINUTE_MS;
 var createClient = (secret, redirectUri) => new google_auth_library.OAuth2Client({
 	clientId: secret.client_id,
 	clientSecret: secret.client_secret,
@@ -251,15 +375,29 @@ var persistRotatedTokens = (client, home) => {
 		});
 	});
 };
-async function getGoogleAccessToken(home) {
-	const saved = await loadGoogleTokens(home);
-	if (!saved?.refresh_token) throw new Error("Google account not linked on this host — ask the user to link their Google account in this app's settings, then retry");
+var REVOKED_GRANT_MESSAGE = "could not obtain a Google access token — the grant may have been revoked; re-link the account";
+var localAccessToken = async (saved, home) => {
+	const presence = await clientSecretPresence(home);
+	if (presence === "ambiguous") await loadClientSecret(home);
+	if (presence === "missing") throw new Error("the saved Google link was created with an OAuth client that is no longer configured on this host — ask the user to link their Google account again in this app's settings");
 	const client = createClient(await loadClientSecret(home));
 	client.setCredentials(saved);
 	persistRotatedTokens(client, home);
 	const { token } = await client.getAccessToken();
-	if (!token) throw new Error("could not obtain a Google access token — the grant may have been revoked; re-link the account");
+	if (!token) throw new Error(REVOKED_GRANT_MESSAGE);
 	return token;
+};
+var brokerAccessToken = async (saved, home) => {
+	if (typeof saved.expiry_date === "number" && saved.access_token && saved.expiry_date - EXPIRY_MARGIN_MS > Date.now()) return saved.access_token;
+	const refreshed = await brokerRefresh(saved.refresh_token ?? "");
+	if (!refreshed.access_token) throw new Error(REVOKED_GRANT_MESSAGE);
+	await saveGoogleTokens(refreshed, home);
+	return refreshed.access_token;
+};
+async function getGoogleAccessToken(home) {
+	const saved = await loadGoogleTokens(home);
+	if (!saved?.refresh_token) throw new Error("Google account not linked on this host — ask the user to link their Google account in this app's settings, then retry");
+	return saved.issuedVia === "broker" ? await brokerAccessToken(saved, home) : await localAccessToken(saved, home);
 }
 var REVOKE_URL = "https://oauth2.googleapis.com/revoke";
 /** Revoke the grant at Google (best-effort) and delete the local token file.
@@ -340,22 +478,49 @@ var buildConsentUrl = (client, codeChallenge, state) => client.generateAuthUrl({
 	code_challenge: codeChallenge,
 	state
 });
+var generatePkce = async () => {
+	const { codeVerifier, codeChallenge } = await new google_auth_library.OAuth2Client().generateCodeVerifierAsync();
+	if (!codeChallenge) throw new Error("failed to derive a PKCE code challenge");
+	return {
+		codeVerifier,
+		codeChallenge
+	};
+};
+var authorizeWithLocalClient = async (secret, server, port, opts) => {
+	const client = createClient(secret, `http://127.0.0.1:${port}${CALLBACK_PATH}`);
+	const { codeVerifier, codeChallenge } = await client.generateCodeVerifierAsync();
+	if (!codeChallenge) throw new Error("failed to derive a PKCE code challenge");
+	const state = (0, node_crypto.randomBytes)(STATE_BYTES).toString("hex");
+	opts.onAuthUrl?.(buildConsentUrl(client, codeChallenge, state));
+	const code = await waitForAuthCode(server, state, opts.timeoutMs ?? AUTH_TIMEOUT_MS);
+	const { tokens } = await client.getToken({
+		code,
+		codeVerifier
+	});
+	if (!tokens.refresh_token) throw new Error("Google returned no refresh token — remove this app under Google Account → Security → Third-party access, then retry");
+	return tokens;
+};
+var authorizeWithBroker = async (server, port, opts) => {
+	const { codeVerifier, codeChallenge } = await generatePkce();
+	const { authUrl, state } = await brokerStart(port, codeChallenge);
+	opts.onAuthUrl?.(authUrl);
+	return await brokerExchange({
+		code: await waitForAuthCode(server, state, opts.timeoutMs ?? AUTH_TIMEOUT_MS),
+		state,
+		codeVerifier
+	});
+};
 async function authorizeGoogle(opts = {}) {
-	const secret = await loadClientSecret(opts.home);
+	const presence = await clientSecretPresence(opts.home);
+	if (presence === "ambiguous") await loadClientSecret(opts.home);
+	const useLocalClient = presence === "found";
 	const { server, port } = await startLoopbackServer();
 	try {
-		const client = createClient(secret, `http://127.0.0.1:${port}${CALLBACK_PATH}`);
-		const { codeVerifier, codeChallenge } = await client.generateCodeVerifierAsync();
-		if (!codeChallenge) throw new Error("failed to derive a PKCE code challenge");
-		const state = (0, node_crypto.randomBytes)(STATE_BYTES).toString("hex");
-		opts.onAuthUrl?.(buildConsentUrl(client, codeChallenge, state));
-		const code = await waitForAuthCode(server, state, opts.timeoutMs ?? AUTH_TIMEOUT_MS);
-		const { tokens } = await client.getToken({
-			code,
-			codeVerifier
-		});
-		if (!tokens.refresh_token) throw new Error("Google returned no refresh token — remove this app under Google Account → Security → Third-party access, then retry");
-		return await saveGoogleTokens(tokens, opts.home);
+		const issuedVia = useLocalClient ? "local" : "broker";
+		return await saveGoogleTokens({
+			...useLocalClient ? await authorizeWithLocalClient(await loadClientSecret(opts.home), server, port, opts) : await authorizeWithBroker(server, port, opts),
+			issuedVia
+		}, opts.home);
 	} finally {
 		server.close();
 	}
@@ -633,6 +798,10 @@ exports.GOOGLE_TASKS_SCOPE = GOOGLE_TASKS_SCOPE;
 exports.MAX_LIST_RESULTS = MAX_LIST_RESULTS;
 exports.assertSafeMimeType = assertSafeMimeType;
 exports.authorizeGoogle = authorizeGoogle;
+exports.brokerBaseUrl = brokerBaseUrl;
+exports.brokerExchange = brokerExchange;
+exports.brokerRefresh = brokerRefresh;
+exports.brokerStart = brokerStart;
 exports.buildMultipartBody = buildMultipartBody;
 exports.calendarApiError = calendarApiError;
 exports.clientSecretPresence = clientSecretPresence;