@agentshouse/kit 0.0.1 → 0.1.0-alpha.1

package/src/google/gateway.js

@@ -0,0 +1,166 @@
+import { googleAccessToken, revokeGoogleAuthorization } from "./oauth.js";
+import { KitRefusal } from "../refusal.js";
+
+const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
+const RETRYABLE_REASONS = new Set(["rateLimitExceeded", "userRateLimitExceeded"]);
+const RETRY_LIMIT = 3;
+const RETRY_DELAY_MAX_MS = 30_000;
+
+function retryDelay(response, now) {
+  const declared = response.headers.get("retry-after");
+  if (declared === null) return 1000;
+  if (/^\d+$/.test(declared)) return Math.min(RETRY_DELAY_MAX_MS, Number(declared) * 1000);
+  const at = Date.parse(declared);
+  return Number.isNaN(at)
+    ? 1000
+    : Math.min(RETRY_DELAY_MAX_MS, Math.max(0, at - now().getTime()));
+}
+
+function abortableSleep(milliseconds, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted === true) {
+      reject(new KitRefusal("kit_command_cancelled"));
+      return;
+    }
+    const timer = setTimeout(finish, milliseconds);
+    function finish() {
+      signal?.removeEventListener("abort", cancel);
+      resolve();
+    }
+    function cancel() {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", cancel);
+      reject(new KitRefusal("kit_command_cancelled"));
+    }
+    signal?.addEventListener("abort", cancel, { once: true });
+  });
+}
+
+async function failureReasons(response) {
+  let answer = null;
+  try {
+    answer = await response.clone().json();
+  } catch {
+    answer = null;
+  }
+  const failures = answer?.error?.errors;
+  if (!Array.isArray(failures)) return [];
+  return failures.flatMap((failure) =>
+    typeof failure?.reason === "string" ? [failure.reason] : [],
+  );
+}
+
+async function googleResponse(options, dependencies) {
+  const fetcher = dependencies.fetch ?? fetch;
+  const now = dependencies.now ?? (() => new Date());
+  const sleep = dependencies.sleep ?? abortableSleep;
+  let accessToken = await googleAccessToken(options, { fetch: fetcher, now });
+  let refreshedAfterUnauthorized = false;
+  for (let attempt = 0; attempt < RETRY_LIMIT; attempt += 1) {
+    let response;
+    try {
+      response = await fetcher(options.url, {
+        method: options.method ?? "GET",
+        headers: {
+          authorization: `Bearer ${accessToken}`,
+          ...(options.headers ?? {}),
+        },
+        signal: options.signal,
+        ...(options.body === undefined ? {} : { body: options.body }),
+      });
+    } catch (error) {
+      if (options.signal?.aborted === true || error?.name === "AbortError") {
+        throw new KitRefusal("kit_command_cancelled");
+      }
+      throw new KitRefusal("google_provider_unavailable");
+    }
+    if (response.status === 401) {
+      if (!refreshedAfterUnauthorized) {
+        accessToken = await googleAccessToken(
+          { ...options, forceRefresh: true },
+          { fetch: fetcher, now },
+        );
+        refreshedAfterUnauthorized = true;
+        attempt -= 1;
+        continue;
+      }
+      await revokeGoogleAuthorization(options.directory, options.instance, options.requiredScopes);
+      throw new KitRefusal("google_authority_revoked");
+    }
+    if (response.status === 403) {
+      const reasons = await failureReasons(response);
+      if (reasons.some((reason) => RETRYABLE_REASONS.has(reason))) {
+        if (attempt + 1 < RETRY_LIMIT) {
+          await sleep(retryDelay(response, now), options.signal);
+          if (options.signal?.aborted === true) throw new KitRefusal("kit_command_cancelled");
+          continue;
+        }
+        throw new KitRefusal("google_provider_unavailable");
+      }
+      if (reasons.includes("insufficientPermissions")) {
+        await revokeGoogleAuthorization(
+          options.directory,
+          options.instance,
+          options.requiredScopes,
+        );
+        throw new KitRefusal("google_scope_revoked");
+      }
+      throw new KitRefusal("google_provider_unavailable");
+    }
+    if (RETRYABLE_STATUS.has(response.status) && attempt + 1 < RETRY_LIMIT) {
+      await sleep(retryDelay(response, now), options.signal);
+      if (options.signal?.aborted === true) throw new KitRefusal("kit_command_cancelled");
+      continue;
+    }
+    if (response.status === 404 && typeof options.notFoundCode === "string") {
+      throw new KitRefusal(options.notFoundCode);
+    }
+    if (response.status === 410 && typeof options.goneCode === "string") {
+      throw new KitRefusal(options.goneCode);
+    }
+    if (!response.ok) throw new KitRefusal("google_provider_unavailable");
+    return response;
+  }
+  throw new KitRefusal("google_provider_unavailable");
+}
+
+export async function googleJson(options, dependencies = {}) {
+  const response = await googleResponse(options, dependencies);
+  let answer = null;
+  try {
+    answer = await response.json();
+  } catch {
+    answer = null;
+  }
+  if (typeof answer !== "object" || answer === null || Array.isArray(answer)) {
+    throw new KitRefusal("google_provider_response_invalid");
+  }
+  return answer;
+}
+
+export async function googleBoundedText(options, limit, dependencies = {}) {
+  const response = await googleResponse(options, dependencies);
+  const declaredLength = response.headers.get("content-length");
+  if (declaredLength !== null && /^\d+$/.test(declaredLength) && Number(declaredLength) > limit) {
+    throw new KitRefusal("google_content_exceeded");
+  }
+  if (response.body === null) return "";
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let bytes = 0;
+  let text = "";
+  try {
+    for (;;) {
+      const part = await reader.read();
+      if (part.done) break;
+      bytes += part.value.byteLength;
+      if (bytes > limit) throw new KitRefusal("google_content_exceeded");
+      text += decoder.decode(part.value, { stream: true });
+    }
+    return text + decoder.decode();
+  } catch (error) {
+    await reader.cancel().catch(() => undefined);
+    if (error instanceof KitRefusal) throw error;
+    throw new KitRefusal("google_provider_response_invalid");
+  }
+}

package/src/google/gmail.js

@@ -0,0 +1,249 @@
+import { ITEM_BODY_MAX_BYTES } from "../contract.js";
+import { KitRefusal } from "../refusal.js";
+import { googleJson } from "./gateway.js";
+import { GOOGLE_SCOPES } from "./oauth.js";
+
+const GMAIL_ORIGIN = "https://gmail.googleapis.com";
+
+function cursorOf(value) {
+  if (value === null) return { mode: "messages", pageToken: null, historyId: null };
+  let cursor;
+  try {
+    cursor = JSON.parse(value);
+  } catch {
+    throw new KitRefusal("google_checkpoint_invalid", "gmail");
+  }
+  if (
+    typeof cursor !== "object" ||
+    cursor === null ||
+    (cursor.mode !== "messages" && cursor.mode !== "history") ||
+    (cursor.pageToken !== null && typeof cursor.pageToken !== "string") ||
+    (cursor.historyId !== null && typeof cursor.historyId !== "string") ||
+    (cursor.mode === "history" && cursor.historyId === null)
+  ) {
+    throw new KitRefusal("google_checkpoint_invalid", "gmail");
+  }
+  return cursor;
+}
+
+function textBody(part) {
+  if (part?.mimeType === "text/plain" && typeof part.body?.data === "string") {
+    try {
+      return Buffer.from(part.body.data, "base64url").toString("utf8");
+    } catch {
+      return null;
+    }
+  }
+  if (!Array.isArray(part?.parts)) return null;
+  for (const child of part.parts) {
+    const body = textBody(child);
+    if (body !== null) return body;
+  }
+  return null;
+}
+
+function header(message, name) {
+  if (!Array.isArray(message.payload?.headers)) return null;
+  const found = message.payload.headers.find(
+    (entry) => typeof entry?.name === "string" && entry.name.toLowerCase() === name,
+  );
+  return typeof found?.value === "string" ? found.value : null;
+}
+
+function normalizedMessage(message) {
+  if (
+    typeof message?.id !== "string" ||
+    typeof message.historyId !== "string" ||
+    !/^\d+$/.test(message.historyId) ||
+    typeof message.internalDate !== "string" ||
+    !/^\d+$/.test(message.internalDate) ||
+    !Array.isArray(message.labelIds) ||
+    message.labelIds.some((label) => typeof label !== "string")
+  ) {
+    throw new KitRefusal("google_provider_response_invalid", "gmail message");
+  }
+  const observedAt = new Date(Number(message.internalDate));
+  if (Number.isNaN(observedAt.getTime())) {
+    throw new KitRefusal("google_provider_response_invalid", "gmail internalDate");
+  }
+  const author = header(message, "from");
+  const subject = header(message, "subject");
+  const plain = textBody(message.payload);
+  const body = plain ?? (typeof message.snippet === "string" ? message.snippet : "");
+  const content = subject === null || body.startsWith(subject) ? body : `${subject}\n\n${body}`;
+  if (Buffer.byteLength(content, "utf8") > ITEM_BODY_MAX_BYTES) {
+    throw new KitRefusal("google_gmail_content_exceeded");
+  }
+  return {
+    namespace: "google/gmail",
+    nativeObjectId: message.id,
+    nativeVersion: message.historyId,
+    providerModifiedAt: observedAt.toISOString(),
+    observedAt: observedAt.toISOString(),
+    body: content,
+    author,
+    url: `https://mail.google.com/mail/u/0/#all/${encodeURIComponent(message.id)}`,
+    attachments: [],
+    container: `google/gmail/${message.labelIds[0] ?? "mail"}`,
+  };
+}
+
+async function currentHistoryId(common, dependencies) {
+  const profile = await googleJson(
+    { ...common, url: `${GMAIL_ORIGIN}/gmail/v1/users/me/profile` },
+    dependencies,
+  );
+  if (typeof profile.historyId !== "string" || !/^\d+$/.test(profile.historyId)) {
+    throw new KitRefusal("google_provider_response_invalid", "gmail profile");
+  }
+  return profile.historyId;
+}
+
+function listUrl(selection, cursor, limit, backfillFloor) {
+  const url = new URL(
+    cursor.mode === "messages"
+      ? "/gmail/v1/users/me/messages"
+      : "/gmail/v1/users/me/history",
+    GMAIL_ORIGIN,
+  );
+  url.searchParams.set("maxResults", `${limit}`);
+  if (cursor.pageToken !== null) url.searchParams.set("pageToken", cursor.pageToken);
+  if (cursor.mode === "messages") {
+    for (const label of selection.labels) url.searchParams.append("labelIds", label);
+    if (backfillFloor !== null && backfillFloor !== undefined) {
+      url.searchParams.set("q", `after:${Math.floor(Date.parse(backfillFloor) / 1000)}`);
+    }
+  } else {
+    url.searchParams.set("startHistoryId", cursor.historyId);
+    url.searchParams.append("historyTypes", "messageAdded");
+    url.searchParams.append("historyTypes", "labelAdded");
+  }
+  return url.toString();
+}
+
+function referencesOf(answer, mode) {
+  if (mode === "messages") {
+    const messages = answer.messages ?? [];
+    if (!Array.isArray(messages) || messages.some((entry) => typeof entry?.id !== "string")) {
+      throw new KitRefusal("google_provider_response_invalid", "gmail messages");
+    }
+    return messages.map((entry) => entry.id);
+  }
+  const history = answer.history ?? [];
+  if (!Array.isArray(history)) throw new KitRefusal("google_provider_response_invalid", "gmail history");
+  const identifiers = [];
+  for (const entry of history) {
+    const groups = [entry?.messagesAdded ?? [], entry?.labelsAdded ?? []];
+    if (groups.some((group) => !Array.isArray(group))) {
+      throw new KitRefusal("google_provider_response_invalid", "gmail history entry");
+    }
+    for (const group of groups) {
+      for (const added of group) {
+        if (typeof added?.message?.id !== "string") {
+          throw new KitRefusal("google_provider_response_invalid", "gmail message id");
+        }
+        identifiers.push(added.message.id);
+      }
+    }
+  }
+  return [...new Set(identifiers)];
+}
+
+export async function gmailPage(options, dependencies = {}) {
+  let cursor = cursorOf(options.cursor);
+  const common = {
+    directory: options.directory,
+    instance: options.instance,
+    client: options.client,
+    requiredScopes: [GOOGLE_SCOPES.gmail],
+    signal: options.signal,
+  };
+  if (cursor.mode === "messages" && cursor.historyId === null) {
+    cursor = { ...cursor, historyId: await currentHistoryId(common, dependencies) };
+  }
+  let answer;
+  try {
+    answer = await googleJson(
+      {
+        ...common,
+        url: listUrl(options.selection, cursor, options.limit, options.backfillFloor),
+        ...(cursor.mode === "history" ? { notFoundCode: "google_history_expired" } : {}),
+      },
+      dependencies,
+    );
+  } catch (error) {
+    if (!(error instanceof KitRefusal) || error.code !== "google_history_expired") throw error;
+    cursor = {
+      mode: "messages",
+      pageToken: null,
+      historyId: await currentHistoryId(common, dependencies),
+    };
+    answer = await googleJson(
+      { ...common, url: listUrl(options.selection, cursor, options.limit, options.backfillFloor) },
+      dependencies,
+    );
+  }
+  if (
+    (answer.nextPageToken !== undefined && typeof answer.nextPageToken !== "string") ||
+    (answer.historyId !== undefined && typeof answer.historyId !== "string")
+  ) {
+    throw new KitRefusal("google_provider_response_invalid", "gmail cursor");
+  }
+  const identifiers = referencesOf(answer, cursor.mode);
+  const items = [];
+  const dropped = [];
+  for (const identifier of identifiers) {
+    let detail;
+    try {
+      detail = await googleJson(
+        {
+          ...common,
+          notFoundCode: "google_gmail_item_missing",
+          url: `${GMAIL_ORIGIN}/gmail/v1/users/me/messages/${encodeURIComponent(identifier)}?format=full`,
+        },
+        dependencies,
+      );
+      const normalized = normalizedMessage(detail);
+      if (options.selection.labels.every((label) => detail.labelIds.includes(label))) {
+        items.push(normalized);
+      }
+    } catch (error) {
+      if (
+        error instanceof KitRefusal &&
+        ["google_gmail_item_missing", "google_gmail_content_exceeded"].includes(error.code)
+      ) {
+        dropped.push({
+          namespace: "google/gmail",
+          nativeObjectId: identifier,
+          nativeVersion: typeof detail?.historyId === "string" ? detail.historyId : null,
+          code: error.code,
+        });
+      } else {
+        throw error;
+      }
+    }
+  }
+  let next;
+  if (cursor.mode === "messages" && answer.nextPageToken !== undefined) {
+    next = { mode: "messages", pageToken: answer.nextPageToken, historyId: cursor.historyId };
+  } else if (cursor.mode === "messages") {
+    next = {
+      mode: "history",
+      pageToken: null,
+      historyId: cursor.historyId,
+    };
+  } else if (answer.nextPageToken !== undefined) {
+    next = { mode: "history", pageToken: answer.nextPageToken, historyId: cursor.historyId };
+  } else {
+    if (typeof answer.historyId !== "string" || !/^\d+$/.test(answer.historyId)) {
+      throw new KitRefusal("google_provider_response_invalid", "gmail history id");
+    }
+    next = { mode: "history", pageToken: null, historyId: answer.historyId };
+  }
+  return {
+    items,
+    dropped,
+    cursor: JSON.stringify(next),
+    more: cursor.mode === "messages" || answer.nextPageToken !== undefined,
+  };
+}

package/src/google/id.js

@@ -0,0 +1 @@
+export const GOOGLE_DRIVE_ID = /^[A-Za-z0-9_-]{1,512}$/;

package/src/google/oauth.js

@@ -0,0 +1,273 @@
+import { createHash, randomBytes, randomInt } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { KitRefusal } from "../refusal.js";
+import { writeNote } from "../state.js";
+
+export const GOOGLE_SCOPES = Object.freeze({
+  gmail: "https://www.googleapis.com/auth/gmail.readonly",
+  calendar: "https://www.googleapis.com/auth/calendar.readonly",
+  drive: "https://www.googleapis.com/auth/drive.readonly",
+});
+
+const AUTHORIZATION_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth";
+const TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+const REFRESH_MARGIN_MS = 60_000;
+const LOOPBACK_PORT_FLOOR = 49152;
+const LOOPBACK_PORT_SPAN = 16384;
+
+function credentialPath(directory, instance) {
+  return join(directory, "state", instance, "credentials", "google.json");
+}
+
+async function rawAuthorization(directory, instance) {
+  const path = credentialPath(directory, instance);
+  let document;
+  try {
+    document = JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw new KitRefusal("google_authorization_unreadable", instance);
+  }
+  if (
+    typeof document !== "object" ||
+    document === null ||
+    !Array.isArray(document.grants) ||
+    document.grants.some(
+      (grant) =>
+        typeof grant !== "object" ||
+        grant === null ||
+        typeof grant.access_token !== "string" ||
+        typeof grant.refresh_token !== "string" ||
+        typeof grant.expires_at !== "string" ||
+        Number.isNaN(Date.parse(grant.expires_at)) ||
+        !Array.isArray(grant.scopes) ||
+        grant.scopes.length === 0 ||
+        grant.scopes.some((scope) => typeof scope !== "string"),
+    )
+  ) {
+    throw new KitRefusal("google_authorization_unreadable", instance);
+  }
+  return document;
+}
+
+async function writeAuthorization(directory, instance, authorization) {
+  await writeNote(credentialPath(directory, instance), authorization);
+}
+
+export async function googleAuthorization(directory, instance) {
+  const authorization = await rawAuthorization(directory, instance);
+  if (authorization === null || authorization.grants.length === 0) return null;
+  return {
+    scopes: [...new Set(authorization.grants.flatMap((grant) => grant.scopes))].sort(),
+    grants: authorization.grants.map((grant) => ({
+      accessToken: grant.access_token,
+      refreshToken: grant.refresh_token,
+      expiresAt: grant.expires_at,
+      scopes: [...grant.scopes],
+    })),
+  };
+}
+
+function requiredScopesOf(value) {
+  if (
+    !Array.isArray(value) ||
+    value.length === 0 ||
+    value.some((scope) => typeof scope !== "string" || scope.length === 0)
+  ) {
+    throw new KitRefusal("google_scope_requirement_invalid");
+  }
+  return value;
+}
+
+export async function revokeGoogleAuthorization(directory, instance, scopes) {
+  const requiredScopes = requiredScopesOf(scopes);
+  const authorization = await rawAuthorization(directory, instance);
+  if (authorization !== null) {
+    await writeAuthorization(directory, instance, {
+      grants: authorization.grants
+        .map((grant) => ({
+          ...grant,
+          scopes: grant.scopes.filter((scope) => !requiredScopes.includes(scope)),
+        }))
+        .filter((grant) => grant.scopes.length > 0),
+    });
+  }
+}
+
+function oauthValue() {
+  return randomBytes(32).toString("base64url");
+}
+
+function authorizationUrl({ clientId, scopes, redirectUri, verifier, state }) {
+  const url = new URL(AUTHORIZATION_ENDPOINT);
+  url.searchParams.set("client_id", clientId);
+  url.searchParams.set("redirect_uri", redirectUri);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("scope", scopes.join(" "));
+  url.searchParams.set("access_type", "offline");
+  url.searchParams.set("code_challenge", createHash("sha256").update(verifier).digest("base64url"));
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", state);
+  url.searchParams.set("prompt", "consent");
+  return url.toString();
+}
+
+function loopbackRedirect(port) {
+  return `http://127.0.0.1:${port ?? LOOPBACK_PORT_FLOOR + randomInt(LOOPBACK_PORT_SPAN)}/`;
+}
+
+function approvedCode(address, redirectUri, state) {
+  const pasted = typeof address === "string" ? address.trim() : "";
+  if (!URL.canParse(pasted)) throw new KitRefusal("google_authorization_rejected");
+  const returned = new URL(pasted);
+  const expected = new URL(redirectUri);
+  if (
+    returned.origin !== expected.origin ||
+    returned.pathname !== expected.pathname ||
+    returned.searchParams.get("state") !== state
+  ) {
+    throw new KitRefusal("google_authorization_rejected");
+  }
+  if (returned.searchParams.has("error")) throw new KitRefusal("google_authorization_declined");
+  const code = returned.searchParams.get("code");
+  if (code === null || code === "") throw new KitRefusal("google_authorization_rejected");
+  return code;
+}
+
+async function tokenRequest(fetcher, body) {
+  let response;
+  try {
+    response = await fetcher(TOKEN_ENDPOINT, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams(body).toString(),
+    });
+  } catch {
+    throw new KitRefusal("google_provider_unavailable");
+  }
+  let answer = null;
+  try {
+    answer = await response.json();
+  } catch {
+    answer = null;
+  }
+  if (!response.ok) {
+    if (answer?.error === "invalid_grant") throw new KitRefusal("google_authority_revoked");
+    throw new KitRefusal("google_provider_unavailable");
+  }
+  if (
+    typeof answer?.access_token !== "string" ||
+    !Number.isInteger(answer.expires_in) ||
+    answer.expires_in < 1 ||
+    (answer.token_type !== undefined && answer.token_type !== "Bearer")
+  ) {
+    throw new KitRefusal("google_provider_response_invalid");
+  }
+  return answer;
+}
+
+function configuredClient(client) {
+  if (
+    typeof client?.id !== "string" ||
+    client.id.length === 0 ||
+    typeof client.secret !== "string" ||
+    client.secret.length === 0
+  ) {
+    throw new KitRefusal("google_oauth_client_unconfigured");
+  }
+  return client;
+}
+
+export async function authorizeGoogle(options, dependencies = {}) {
+  const client = configuredClient(options.client);
+  const stored = await rawAuthorization(options.directory, options.instance);
+  const scopes = [...new Set(options.scopes)];
+  const covered = stored?.grants.some((grant) =>
+    scopes.every((scope) => grant.scopes.includes(scope)),
+  );
+  if (covered === true) return { status: "skipped", requestedScopes: [] };
+  const verifier = oauthValue();
+  const state = oauthValue();
+  const redirectUri = loopbackRedirect(dependencies.loopbackPort);
+  const address = await options.approve({
+    url: authorizationUrl({ clientId: client.id, scopes, redirectUri, verifier, state }),
+    redirectUri,
+  });
+  const code = approvedCode(address, redirectUri, state);
+  const now = dependencies.now?.() ?? new Date();
+  const token = await tokenRequest(dependencies.fetch ?? fetch, {
+    client_id: client.id,
+    client_secret: client.secret,
+    code,
+    code_verifier: verifier,
+    grant_type: "authorization_code",
+    redirect_uri: redirectUri,
+  });
+  const refreshToken = token.refresh_token;
+  if (typeof refreshToken !== "string" || refreshToken.length === 0) {
+    throw new KitRefusal("google_authorization_rejected");
+  }
+  const returnedScopes =
+    typeof token.scope === "string" ? token.scope.split(/\s+/).filter(Boolean) : [];
+  if (returnedScopes.length > 0 && scopes.some((scope) => !returnedScopes.includes(scope))) {
+    throw new KitRefusal("google_authorization_rejected");
+  }
+  const grantedScopes = [...new Set(returnedScopes.length === 0 ? scopes : returnedScopes)].sort();
+  const key = grantedScopes.join("\n");
+  const grants = (stored?.grants ?? []).filter((grant) => [...grant.scopes].sort().join("\n") !== key);
+  await writeAuthorization(options.directory, options.instance, {
+    grants: [
+      ...grants,
+      {
+        access_token: token.access_token,
+        refresh_token: refreshToken,
+        expires_at: new Date(now.getTime() + token.expires_in * 1000).toISOString(),
+        scopes: grantedScopes,
+      },
+    ],
+  });
+  return { status: "ready", requestedScopes: scopes };
+}
+
+export async function googleAccessToken(options, dependencies = {}) {
+  const stored = await rawAuthorization(options.directory, options.instance);
+  const requiredScopes = requiredScopesOf(options.requiredScopes);
+  const grant = stored?.grants
+    .filter((candidate) => requiredScopes.every((scope) => candidate.scopes.includes(scope)))
+    .sort((left, right) => left.scopes.length - right.scopes.length)[0];
+  if (grant === undefined) {
+    throw new KitRefusal("google_authorization_required", options.instance);
+  }
+  const now = dependencies.now?.() ?? new Date();
+  if (options.forceRefresh !== true && Date.parse(grant.expires_at) - now.getTime() > REFRESH_MARGIN_MS) {
+    return grant.access_token;
+  }
+  const client = configuredClient(options.client);
+  let token;
+  try {
+    token = await tokenRequest(dependencies.fetch ?? fetch, {
+      client_id: client.id,
+      client_secret: client.secret,
+      refresh_token: grant.refresh_token,
+      grant_type: "refresh_token",
+    });
+  } catch (error) {
+    if (error instanceof KitRefusal && error.code === "google_authority_revoked") {
+      await revokeGoogleAuthorization(options.directory, options.instance, grant.scopes);
+    }
+    throw error;
+  }
+  await writeAuthorization(options.directory, options.instance, {
+    grants: stored.grants.map((candidate) =>
+      candidate === grant
+        ? {
+            ...candidate,
+            access_token: token.access_token,
+            expires_at: new Date(now.getTime() + token.expires_in * 1000).toISOString(),
+          }
+        : candidate,
+    ),
+  });
+  return token.access_token;
+}