@digestseo/mcp-gsc 0.3.1 → 0.4.0

package/src/indexed-pages-range.ts

@@ -0,0 +1,54 @@
+import { assertDateRange } from './date-validation';
+
+export interface IndexedPagesDateRange {
+  startDate: string;
+  endDate: string;
+}
+
+function addUtcDays(date: string, days: number): string {
+  const result = new Date(`${date}T00:00:00Z`);
+  result.setUTCDate(result.getUTCDate() + days);
+  return result.toISOString().slice(0, 10);
+}
+
+export function resolveIndexedPagesDateRange(
+  startDate: string | undefined,
+  endDate: string | undefined,
+  today: string,
+): IndexedPagesDateRange {
+  const latestCompleteDate = addUtcDays(today, -3);
+
+  if (!startDate && !endDate) {
+    return {
+      startDate: addUtcDays(latestCompleteDate, -29),
+      endDate: latestCompleteDate,
+    };
+  }
+
+  if (!startDate) {
+    return {
+      startDate: addUtcDays(endDate!, -29),
+      endDate: endDate!,
+    };
+  }
+
+  if (!endDate) {
+    if (startDate > latestCompleteDate) {
+      throw new Error(
+        `start_date must be on or before ${latestCompleteDate} when end_date is omitted. ` +
+        'The generated end_date cannot be later than the latest complete date.',
+      );
+    }
+    const generatedEndDate = addUtcDays(startDate, 29);
+    return {
+      startDate,
+      endDate:
+        generatedEndDate > latestCompleteDate
+          ? latestCompleteDate
+          : generatedEndDate,
+    };
+  }
+
+  assertDateRange(startDate, endDate);
+  return { startDate, endDate };
+}

package/src/indexing-property-authorization.ts

@@ -0,0 +1,119 @@
+export interface SearchConsoleSite {
+  siteUrl: string;
+  permissionLevel: string;
+}
+
+const SITE_OWNER_PERMISSION = 'siteOwner';
+const DOMAIN_PROPERTY_PREFIX = 'sc-domain:';
+
+function parseHttpUrl(value: string, fieldName: string): URL {
+  if (value !== value.trim() || !/^https?:\/\//i.test(value)) {
+    throw new Error(`${fieldName} must be a fully qualified HTTP or HTTPS URL.`);
+  }
+
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`${fieldName} must be a fully qualified HTTP or HTTPS URL.`);
+  }
+
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(`${fieldName} must use the HTTP or HTTPS scheme.`);
+  }
+  if (!url.hostname) {
+    throw new Error(`${fieldName} must include a hostname.`);
+  }
+  if (url.username || url.password) {
+    throw new Error(`${fieldName} must not include userinfo.`);
+  }
+
+  return url;
+}
+
+function parseDomainProperty(siteUrl: string): string {
+  const domain = siteUrl.slice(DOMAIN_PROPERTY_PREFIX.length);
+  if (!domain || /[/?#@:]/.test(domain)) {
+    throw new Error('site_url is not a valid Search Console domain property.');
+  }
+
+  const parsed = parseHttpUrl(`https://${domain}`, 'site_url');
+  if (parsed.pathname !== '/' || parsed.search || parsed.hash || parsed.port) {
+    throw new Error('site_url is not a valid Search Console domain property.');
+  }
+
+  return parsed.hostname;
+}
+
+function normalizeSiteUrl(siteUrl: string): string {
+  if (siteUrl.startsWith(DOMAIN_PROPERTY_PREFIX)) {
+    return `${DOMAIN_PROPERTY_PREFIX}${parseDomainProperty(siteUrl)}`;
+  }
+
+  const parsed = parseHttpUrl(siteUrl, 'site_url');
+  if (parsed.search || parsed.hash) {
+    throw new Error('site_url must not include a query string or fragment.');
+  }
+  return parsed.href;
+}
+
+function isWithinUrlPrefix(target: URL, property: URL): boolean {
+  if (target.origin !== property.origin) return false;
+
+  const propertyPath = property.pathname;
+  if (propertyPath === '/') return true;
+  const descendantPrefix = propertyPath.endsWith('/')
+    ? propertyPath
+    : `${propertyPath}/`;
+
+  return (
+    target.pathname === propertyPath ||
+    target.pathname.startsWith(descendantPrefix)
+  );
+}
+
+function isWithinDomainProperty(target: URL, domain: string): boolean {
+  return target.hostname === domain || target.hostname.endsWith(`.${domain}`);
+}
+
+/**
+ * Confirms that an Indexing API URL is contained by an owner-level Search
+ * Console property available to the authenticated account. URL parsing avoids
+ * string-prefix and userinfo lookalike bypasses before any page fetch occurs.
+ */
+export function assertIndexingUrlAuthorized(
+  url: string,
+  siteUrl: string,
+  sites: SearchConsoleSite[],
+): void {
+  const target = parseHttpUrl(url, 'url');
+  const normalizedSiteUrl = normalizeSiteUrl(siteUrl);
+  const authorizedSite = sites.find((site) => {
+    if (site.permissionLevel !== SITE_OWNER_PERMISSION) return false;
+    try {
+      return normalizeSiteUrl(site.siteUrl) === normalizedSiteUrl;
+    } catch {
+      return false;
+    }
+  });
+
+  if (!authorizedSite) {
+    throw new Error(
+      'site_url must be a Search Console property where the authenticated Google account is an owner.',
+    );
+  }
+
+  if (normalizedSiteUrl.startsWith(DOMAIN_PROPERTY_PREFIX)) {
+    if (isWithinDomainProperty(target, parseDomainProperty(normalizedSiteUrl))) {
+      return;
+    }
+  } else if (isWithinUrlPrefix(target, new URL(normalizedSiteUrl))) {
+    return;
+  }
+
+  throw new Error('url must belong to the authorized site_url Search Console property.');
+}
+
+export function assertIndexingRequestUrl(url: string): void {
+  parseHttpUrl(url, 'url');
+}

package/src/pending-auth-state.ts

@@ -0,0 +1,87 @@
+const PENDING_AUTH_TTL_MS = 10 * 60 * 1000;
+
+export interface PendingAuthRequest {
+  claudeAuthRequest: unknown;
+  created_at: number;
+  expires_at: number;
+}
+
+interface PendingAuthStateEnv {
+  PENDING_AUTH_STATE: DurableObjectNamespace;
+}
+
+interface PendingAuthStateStub {
+  store(claudeAuthRequest: unknown): Promise<void>;
+  consume(): Promise<PendingAuthRequest | null>;
+}
+
+/**
+ * One instance is addressed by one OAuth nonce. Its storage transaction makes
+ * consumption a single read-check-delete operation, even for concurrent
+ * callbacks routed to the same Durable Object.
+ */
+/**
+ * Storage-only pending authorization state. Keeping this independent from the
+ * Worker runtime lets the single-use/expiry semantics stay covered by the
+ * fast Node test suite while the exported Durable Object delegates to it.
+ */
+export class PendingAuthStateStore {
+  constructor(
+    private readonly storage: DurableObjectStorage,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  async store(claudeAuthRequest: unknown): Promise<void> {
+    const created_at = this.now();
+    const record: PendingAuthRequest = {
+      claudeAuthRequest,
+      created_at,
+      expires_at: created_at + PENDING_AUTH_TTL_MS,
+    };
+
+    await Promise.all([
+      this.storage.put('pending', record),
+      this.storage.setAlarm(record.expires_at),
+    ]);
+  }
+
+  async consume(): Promise<PendingAuthRequest | null> {
+    return this.storage.transaction(async (txn) => {
+      const record = await txn.get<PendingAuthRequest>('pending');
+      if (!record) return null;
+
+      await txn.delete('pending');
+      await txn.deleteAlarm();
+
+      return record.expires_at > this.now() ? record : null;
+    });
+  }
+
+  async alarm(): Promise<void> {
+    await this.storage.deleteAll();
+  }
+}
+
+function getPendingAuthStateStub(
+  env: PendingAuthStateEnv,
+  nonce: string,
+): PendingAuthStateStub {
+  return env.PENDING_AUTH_STATE.get(
+    env.PENDING_AUTH_STATE.idFromName(nonce),
+  ) as unknown as PendingAuthStateStub;
+}
+
+export async function stashPendingAuth(
+  env: PendingAuthStateEnv,
+  nonce: string,
+  claudeAuthRequest: unknown,
+): Promise<void> {
+  await getPendingAuthStateStub(env, nonce).store(claudeAuthRequest);
+}
+
+export async function consumePendingAuth(
+  env: PendingAuthStateEnv,
+  nonce: string,
+): Promise<PendingAuthRequest | null> {
+  return getPendingAuthStateStub(env, nonce).consume();
+}

package/src/quick-wins-schema.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { SEARCH_CONSOLE_DATE_SCHEMA } from './date-validation';
+
+const POSITION_RANGE_ERROR = {
+  message: 'min_position must be less than or equal to max_position.',
+  path: ['max_position'],
+};
+
+const QUICK_WINS_THRESHOLDS_SHAPE = {
+  min_impressions: z.number().int().min(0).default(100).describe('Minimum impressions required to consider a query. Must be at least 0. Default is 100.'),
+  min_position: z.number().positive().default(8).describe('Minimum average position to target (inclusive). Must be greater than 0. Default is 8.'),
+  max_position: z.number().positive().default(20).describe('Maximum average position to target (inclusive). Must be greater than 0. Default is 20.'),
+};
+
+export function createQuickWinsInputSchema(siteUrlDescription: string) {
+  return z
+    .object({
+      site_url: z.string().describe(siteUrlDescription),
+      start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('Start date (inclusive) in YYYY-MM-DD format.'),
+      end_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('End date (inclusive) in YYYY-MM-DD format. Note the 2-3 day GSC data lag.'),
+      ...QUICK_WINS_THRESHOLDS_SHAPE,
+    })
+    .refine(
+      ({ min_position, max_position }) => min_position <= max_position,
+      POSITION_RANGE_ERROR,
+    );
+}

package/src/storage.ts

@@ -1,98 +1,65 @@
-import { encryptToken, decryptToken } from './crypto';
-
-interface StorageEnv {
-  OAUTH_KV: KVNamespace;
-  USER_KV: KVNamespace;
-  TOKEN_ENCRYPTION_KEY: string;
-}
-
-const PENDING_TTL_SECONDS = 600;
-
-export interface PendingAuthRequest {
-  claudeAuthRequest: unknown;
-  created_at: number;
-}
-
-export async function stashPendingAuth(
-  env: StorageEnv,
-  nonce: string,
-  claudeAuthRequest: unknown,
-): Promise<void> {
-  const record: PendingAuthRequest = {
-    claudeAuthRequest,
-    created_at: Date.now(),
-  };
-  await env.OAUTH_KV.put(`pending:${nonce}`, JSON.stringify(record), {
-    expirationTtl: PENDING_TTL_SECONDS,
-  });
-}
-
-export async function popPendingAuth(
-  env: StorageEnv,
-  nonce: string,
-): Promise<PendingAuthRequest | null> {
-  const key = `pending:${nonce}`;
-  const raw = await env.OAUTH_KV.get(key);
-  if (!raw) return null;
-  await env.OAUTH_KV.delete(key);
-  return JSON.parse(raw) as PendingAuthRequest;
-}
-
-export interface UserRecord {
-  email: string;
-  encrypted_refresh_token: string;
-  iv: string;
-  created_at: number;
-  updated_at: number;
-}
-
-export async function saveUser(
-  env: StorageEnv,
-  googleId: string,
-  email: string,
-  refreshToken: string,
-): Promise<void> {
-  const { ciphertext, iv } = await encryptToken(
-    refreshToken,
-    env.TOKEN_ENCRYPTION_KEY,
-  );
-  const existing = await getUser(env, googleId);
-  const now = Date.now();
-  const record: UserRecord = {
-    email,
-    encrypted_refresh_token: ciphertext,
-    iv,
-    created_at: existing?.created_at ?? now,
-    updated_at: now,
-  };
-  await env.USER_KV.put(`user:${googleId}`, JSON.stringify(record));
-}
-
-export async function getUser(
-  env: StorageEnv,
-  googleId: string,
-): Promise<UserRecord | null> {
-  const raw = await env.USER_KV.get(`user:${googleId}`);
-  if (!raw) return null;
-  return JSON.parse(raw) as UserRecord;
-}
-
-export async function deleteUser(
-  env: StorageEnv,
-  googleId: string,
-): Promise<void> {
-  await env.USER_KV.delete(`user:${googleId}`);
-}
-
-export async function getDecryptedRefreshToken(
-  env: StorageEnv,
-  googleId: string,
-): Promise<string | null> {
-  const user = await getUser(env, googleId);
-  if (!user) return null;
-  return await decryptToken(
-    user.encrypted_refresh_token,
-    user.iv,
-    env.TOKEN_ENCRYPTION_KEY,
-  );
-}
+import { encryptToken, decryptToken } from './crypto';
+
+interface StorageEnv {
+  USER_KV: KVNamespace;
+  TOKEN_ENCRYPTION_KEY: string;
+}
+
+export interface UserRecord {
+  email: string;
+  encrypted_refresh_token: string;
+  iv: string;
+  created_at: number;
+  updated_at: number;
+}
+
+export async function saveUser(
+  env: StorageEnv,
+  googleId: string,
+  email: string,
+  refreshToken: string,
+): Promise<void> {
+  const { ciphertext, iv } = await encryptToken(
+    refreshToken,
+    env.TOKEN_ENCRYPTION_KEY,
+  );
+  const existing = await getUser(env, googleId);
+  const now = Date.now();
+  const record: UserRecord = {
+    email,
+    encrypted_refresh_token: ciphertext,
+    iv,
+    created_at: existing?.created_at ?? now,
+    updated_at: now,
+  };
+  await env.USER_KV.put(`user:${googleId}`, JSON.stringify(record));
+}
+
+export async function getUser(
+  env: StorageEnv,
+  googleId: string,
+): Promise<UserRecord | null> {
+  const raw = await env.USER_KV.get(`user:${googleId}`);
+  if (!raw) return null;
+  return JSON.parse(raw) as UserRecord;
+}
+
+export async function deleteUser(
+  env: StorageEnv,
+  googleId: string,
+): Promise<void> {
+  await env.USER_KV.delete(`user:${googleId}`);
+}
+
+export async function getDecryptedRefreshToken(
+  env: StorageEnv,
+  googleId: string,
+): Promise<string | null> {
+  const user = await getUser(env, googleId);
+  if (!user) return null;
+  return await decryptToken(
+    user.encrypted_refresh_token,
+    user.iv,
+    env.TOKEN_ENCRYPTION_KEY,
+  );
+}

package/src/tool-rate-limit.ts

@@ -0,0 +1,231 @@
+const MINUTE_MS = 60 * 1000;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
+
+export interface ToolRateLimitPolicy {
+  /** The coordination bucket shared by the tools in this policy. */
+  category: string;
+  tools: readonly string[];
+  windowMs: number;
+  userLimit: number;
+  /**
+   * A project-wide cap is used only where Google publishes a small, shared
+   * project quota. It is intentionally absent for ordinary GSC operations.
+   */
+  projectLimit?: number;
+}
+
+/**
+ * Limits apply before an upstream request is made. The values are intentionally
+ * conservative relative to Google's published quotas, because a self-hosted
+ * deployment can have multiple authenticated users sharing one Cloud project.
+ *
+ * Sources:
+ * - https://developers.google.com/webmaster-tools/limits
+ * - https://developers.google.com/search/apis/indexing-api/v3/quota-pricing
+ */
+export const TOOL_RATE_LIMIT_POLICIES = {
+  search_analytics: {
+    category: 'search-analytics',
+    tools: [
+      'analytics.query',
+      'insights.page_queries',
+      'insights.query_pages',
+      'insights.quick_wins',
+      'insights.cannibalization',
+      'insights.content_decay',
+      'indexing.list_pages',
+      'analytics.compare',
+    ],
+    // GSC measures Search Analytics short-term load in 10-minute windows.
+    windowMs: 10 * MINUTE_MS,
+    userLimit: 30,
+  },
+  url_inspection: {
+    category: 'url-inspection',
+    tools: ['urls.inspect', 'urls.inspect_many'],
+    // This is one percent of GSC's published 2,000
+    // inspections-per-site-per-day quota for each user.
+    windowMs: DAY_MS,
+    userLimit: 20,
+  },
+  search_console_writes: {
+    category: 'search-console-write',
+    tools: ['sites.add', 'sites.delete', 'sitemaps.submit', 'sitemaps.delete'],
+    // Mutation safety guard, far below GSC's 200 requests-per-minute
+    // per-user limit for non-Search-Analytics resources.
+    windowMs: HOUR_MS,
+    userLimit: 10,
+  },
+  indexing_request: {
+    category: 'indexing-request',
+    tools: ['indexing.request'],
+    // Google defaults to 200 publish requests per project per day. Two per
+    // user reserves the default quota for up to 100 authenticated users.
+    windowMs: DAY_MS,
+    userLimit: 2,
+    projectLimit: 200,
+  },
+  weekly_digest: {
+    category: 'weekly-digest',
+    tools: ['reports.weekly_digest'],
+    // A digest makes five Search Analytics requests, so it has its own bucket.
+    windowMs: HOUR_MS,
+    userLimit: 6,
+  },
+} as const satisfies Record<string, ToolRateLimitPolicy>;
+
+export type ToolRateLimitCategory = keyof typeof TOOL_RATE_LIMIT_POLICIES;
+export type RateLimitedToolName =
+  (typeof TOOL_RATE_LIMIT_POLICIES)[ToolRateLimitCategory]['tools'][number];
+
+const POLICY_BY_TOOL = new Map<string, ToolRateLimitPolicy>(
+  Object.values(TOOL_RATE_LIMIT_POLICIES).flatMap((policy) =>
+    policy.tools.map((tool) => [tool, policy] as const),
+  ),
+);
+
+interface RateLimitWindow {
+  window_started_at: number;
+  count: number;
+}
+
+export interface ToolRateLimitResult {
+  allowed: boolean;
+  retry_after_ms?: number;
+}
+
+interface ToolRateLimiterEnv {
+  TOOL_RATE_LIMITER: DurableObjectNamespace;
+}
+
+interface ToolRateLimiterStub {
+  take(
+    userBucket: string,
+    policy: ToolRateLimitPolicy,
+    units?: number,
+  ): Promise<ToolRateLimitResult>;
+}
+
+function currentWindow(
+  value: RateLimitWindow | undefined,
+  now: number,
+  windowMs: number,
+): RateLimitWindow {
+  if (!value || now >= value.window_started_at + windowMs) {
+    return { window_started_at: now, count: 0 };
+  }
+  return value;
+}
+
+function retryAfterMs(window: RateLimitWindow, now: number, windowMs: number): number {
+  return Math.max(0, window.window_started_at + windowMs - now);
+}
+
+/**
+ * Coordinates one policy category. Ordinary categories are sharded by the
+ * authenticated user's hashed bucket. Indexing uses one category instance so
+ * its small Google project quota can be enforced together with user limits.
+ */
+export class ToolRateLimiterCore {
+  constructor(
+    private readonly state: DurableObjectState,
+    _env: unknown,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  async take(
+    userBucket: string,
+    policy: ToolRateLimitPolicy,
+    units = 1,
+  ): Promise<ToolRateLimitResult> {
+    if (!Number.isInteger(units) || units < 1) {
+      throw new Error('Rate-limit units must be a positive integer.');
+    }
+    return this.state.storage.transaction(async (txn) => {
+      const now = this.now();
+      const userKey = `user:${userBucket}`;
+      const userWindow = currentWindow(
+        await txn.get<RateLimitWindow>(userKey),
+        now,
+        policy.windowMs,
+      );
+      const projectWindow = policy.projectLimit === undefined
+        ? undefined
+        : currentWindow(
+          await txn.get<RateLimitWindow>('project'),
+          now,
+          policy.windowMs,
+        );
+
+      const userExceeded = userWindow.count + units > policy.userLimit;
+      const projectExceeded = projectWindow !== undefined
+        && projectWindow.count + units > policy.projectLimit!;
+      if (userExceeded || projectExceeded) {
+        const waits = [
+          ...(userExceeded
+            ? [retryAfterMs(userWindow, now, policy.windowMs)]
+            : []),
+          ...(projectExceeded && projectWindow
+            ? [retryAfterMs(projectWindow, now, policy.windowMs)]
+            : []),
+        ];
+        return {
+          allowed: false,
+          // If both limits apply, waiting for the longer window guarantees the
+          // retry will not immediately encounter the other limit.
+          retry_after_ms: Math.max(...waits),
+        };
+      }
+
+      await txn.put(userKey, { ...userWindow, count: userWindow.count + units });
+      if (projectWindow) {
+        await txn.put('project', {
+          ...projectWindow,
+          count: projectWindow.count + units,
+        });
+      }
+      return { allowed: true };
+    });
+  }
+}
+
+export function getToolRateLimitPolicy(toolName: string): ToolRateLimitPolicy | undefined {
+  return POLICY_BY_TOOL.get(toolName);
+}
+
+async function userBucketFor(googleId: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(googleId),
+  );
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+function getToolRateLimiterStub(
+  env: ToolRateLimiterEnv,
+  policy: ToolRateLimitPolicy,
+  userBucket: string,
+): ToolRateLimiterStub {
+  // The Indexing API's low project-wide quota is the coordination atom for
+  // that category. All other policies are sharded by user and category.
+  const name = policy.projectLimit === undefined
+    ? `${policy.category}:${userBucket}`
+    : policy.category;
+  return env.TOOL_RATE_LIMITER.get(
+    env.TOOL_RATE_LIMITER.idFromName(name),
+  ) as unknown as ToolRateLimiterStub;
+}
+
+export async function enforceToolRateLimit(
+  env: ToolRateLimiterEnv,
+  googleId: string,
+  toolName: string,
+  units = 1,
+): Promise<ToolRateLimitResult> {
+  const policy = getToolRateLimitPolicy(toolName);
+  if (!policy) return { allowed: true };
+
+  const userBucket = await userBucketFor(googleId);
+  return getToolRateLimiterStub(env, policy, userBucket).take(userBucket, policy, units);
+}