Extract @executor/plugin-oauth2 shared helpers (#247)

## Summary
- New `@executor/plugin-oauth2` package: generic, provider-agnostic OAuth 2.0 helpers (PKCE, authorization URL, code exchange, refresh, refresh-skew predicate, typed `OAuth2Error`).
- Ports `google-discovery` to use the shared package — its `oauth.ts` shrinks from ~150 lines to ~85, with Google-specific behavior (`access_type=offline`, `prompt=consent`, `include_granted_scopes=true`, hardcoded URLs) preserved via the `extraParams` escape hatch and a thin wrapper.
- 33-test fidelity suite encodes every real-world quirk the prior implementation handled, so future "simplifications" fail loudly.

## Why
We were about to copy this code a third time for OpenAPI L3 OAuth onboarding. Extracting it now keeps the call sites consistent and gives us one place to fix bugs. The fidelity suite is the contract — the goal of extraction was zero behavioral change in `google-discovery`, and the existing google-discovery tests verify that.

## Fidelity behaviors locked in by tests
- **PKCE**: 48-byte verifier matches `^[A-Za-z0-9_-]{43,128}$`, RFC 7636 Appendix A test vector for `S256(verifier) == challenge`, uniqueness across 50 invocations.
- **`decodeTokenResponse`**: rejects non-JSON bodies (HTML 5xx pages), rejects JSON arrays/primitives, accepts `expires_in` as **string OR number** (Azure et al.), error fallback chain (`error_description` → `error` → `status N`), rejects 200 with empty / missing `access_token`.
- **Token endpoint POST**: `application/x-www-form-urlencoded` + `accept: application/json`, `AbortSignal.timeout(20_000)`, body-based client_secret by default, optional HTTP Basic auth (`clientAuth: "basic"`) for Stripe-style providers, `OAuth2Error` propagation through the Effect failure channel.
- **`buildAuthorizationUrl`**: standard PKCE params, custom scope separator (comma for legacy providers), `extraParams` merge does not drop standard params, preserves pre-existing query params on the authorization URL.
- **`refreshAccessToken`**: `grant_type=refresh_token`, scope omitted when empty, included when provided.
- **`shouldRefreshToken`**: `null` expiry never refreshes, 60s default skew, custom skew respected.

## Test plan
- [x] `bunx vitest run` in `packages/plugins/oauth2` → 33 passed
- [x] `bunx vitest run` in `packages/plugins/google-discovery` → 6 passed (existing regression gate)
- [x] `bunx turbo run typecheck` → 29 packages clean
- [x] `bunx turbo run test` → all 23 task suites pass

Author: RhysSullivan

bun.lock

@@ -49,6 +49,7 @@
   "dependencies": {
     "@effect/platform": "catalog:",
     "@executor/api": "workspace:*",
+    "@executor/plugin-oauth2": "workspace:*",
     "@executor/sdk": "workspace:*",
     "effect": "catalog:"
   },

packages/plugins/google-discovery/package.json

@@ -1,6 +1,8 @@
 import { Effect, Layer, Option } from "effect";
 import { FetchHttpClient, HttpClient, HttpClientRequest } from "@effect/platform";
 
+import { shouldRefreshToken } from "@executor/plugin-oauth2";
+
 import {
   type ScopeId,
   type SecretId,
@@ -19,8 +21,6 @@ import {
 } from "./types";
 import { refreshAccessToken } from "./oauth";
 
-const OAUTH_REFRESH_SKEW_MS = 60_000;
-
 const SAFE_METHODS = new Set(["get", "head", "options"]);
 
 const stringValuesFromParameter = (value: unknown, repeated: boolean): string[] => {
@@ -91,11 +91,9 @@ const resolveOAuthAccessToken = (input: {
     }
 
     const auth = input.source.auth;
-    const now = Date.now();
     const needsRefresh =
       auth.refreshTokenSecretId !== null &&
-      auth.expiresAt !== null &&
-      auth.expiresAt <= now + OAUTH_REFRESH_SKEW_MS;
+      shouldRefreshToken({ expiresAt: auth.expiresAt });
 
     if (!needsRefresh) {
       return yield* input.secrets.resolve(auth.accessTokenSecretId as SecretId, input.scopeId).pipe(

packages/plugins/google-discovery/src/sdk/invoke.ts

@@ -1,151 +1,91 @@
-import { createHash, randomBytes } from "node:crypto";
+// ---------------------------------------------------------------------------
+// Google-specific thin wrapper over @executor/plugin-oauth2.
+//
+// All standards-compliant OAuth 2.0 logic lives in the shared package. This
+// file only carries the bits Google needs that are NOT in the spec:
+//   - Hardcoded authorization URL (accounts.google.com/o/oauth2/v2/auth)
+//   - access_type=offline                — required to receive a refresh_token
+//   - prompt=consent                     — forces re-consent so refresh_token is reissued
+//   - include_granted_scopes=true        — Google's incremental authorization
+// ---------------------------------------------------------------------------
 
 import { Effect } from "effect";
 
+import {
+  buildAuthorizationUrl,
+  createPkceCodeVerifier as sharedCreatePkceCodeVerifier,
+  exchangeAuthorizationCode as sharedExchangeAuthorizationCode,
+  refreshAccessToken as sharedRefreshAccessToken,
+  type OAuth2TokenResponse,
+} from "@executor/plugin-oauth2";
+
 import { GoogleDiscoveryOAuthError } from "./errors";
 
-export type OAuth2TokenResponse = {
-  readonly access_token: string;
-  readonly token_type?: string;
-  readonly refresh_token?: string;
-  readonly expires_in?: number;
-  readonly scope?: string;
-};
+const GOOGLE_AUTHORIZATION_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
 
-const encodeBase64Url = (input: Buffer): string =>
-  input.toString("base64").replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+const GOOGLE_EXTRA_AUTHORIZATION_PARAMS = {
+  access_type: "offline",
+  include_granted_scopes: "true",
+  prompt: "consent",
+} as const;
 
-export const createPkceCodeVerifier = (): string => encodeBase64Url(randomBytes(48));
+export type { OAuth2TokenResponse as OAuth2TokenResponse };
 
-const createPkceCodeChallenge = (verifier: string): string =>
-  encodeBase64Url(createHash("sha256").update(verifier).digest());
+export const createPkceCodeVerifier = sharedCreatePkceCodeVerifier;
 
 export const buildGoogleAuthorizationUrl = (input: {
   readonly clientId: string;
   readonly redirectUrl: string;
   readonly scopes: readonly string[];
   readonly state: string;
   readonly codeVerifier: string;
-}): string => {
-  const url = new URL("https://accounts.google.com/o/oauth2/v2/auth");
-  url.searchParams.set("client_id", input.clientId);
-  url.searchParams.set("redirect_uri", input.redirectUrl);
-  url.searchParams.set("response_type", "code");
-  url.searchParams.set("scope", input.scopes.join(" "));
-  url.searchParams.set("state", input.state);
-  url.searchParams.set("code_challenge_method", "S256");
-  url.searchParams.set("code_challenge", createPkceCodeChallenge(input.codeVerifier));
-  url.searchParams.set("access_type", "offline");
-  url.searchParams.set("include_granted_scopes", "true");
-  url.searchParams.set("prompt", "consent");
-  return url.toString();
-};
-
-const decodeTokenResponse = async (response: Response): Promise<OAuth2TokenResponse> => {
-  const rawText = await response.text();
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(rawText);
-  } catch {
-    throw new Error(`OAuth token endpoint returned non-JSON response (${response.status})`);
-  }
-
-  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`OAuth token endpoint returned invalid JSON payload (${response.status})`);
-  }
-
-  const record = parsed as Record<string, unknown>;
-  const accessToken =
-    typeof record.access_token === "string" && record.access_token.length > 0
-      ? record.access_token
-      : null;
-
-  if (!response.ok) {
-    const description =
-      typeof record.error_description === "string"
-        ? record.error_description
-        : typeof record.error === "string"
-          ? record.error
-          : `status ${response.status}`;
-    throw new Error(`OAuth token exchange failed: ${description}`);
-  }
-
-  if (accessToken === null) {
-    throw new Error("OAuth token endpoint did not return an access_token");
-  }
-
-  return {
-    access_token: accessToken,
-    token_type: typeof record.token_type === "string" ? record.token_type : undefined,
-    refresh_token: typeof record.refresh_token === "string" ? record.refresh_token : undefined,
-    expires_in:
-      typeof record.expires_in === "number"
-        ? record.expires_in
-        : typeof record.expires_in === "string"
-          ? Number(record.expires_in)
-          : undefined,
-    scope: typeof record.scope === "string" ? record.scope : undefined,
-  };
-};
-
-const postToTokenEndpoint = (body: URLSearchParams) =>
-  Effect.tryPromise({
-    try: async () => {
-      const response = await fetch("https://oauth2.googleapis.com/token", {
-        method: "POST",
-        headers: {
-          "content-type": "application/x-www-form-urlencoded",
-          accept: "application/json",
-        },
-        body,
-        signal: AbortSignal.timeout(20_000),
-      });
-      return decodeTokenResponse(response);
-    },
-    catch: (cause) =>
-      new GoogleDiscoveryOAuthError({
-        message: cause instanceof Error ? cause.message : String(cause),
-      }),
+}): string =>
+  buildAuthorizationUrl({
+    authorizationUrl: GOOGLE_AUTHORIZATION_URL,
+    clientId: input.clientId,
+    redirectUrl: input.redirectUrl,
+    scopes: input.scopes,
+    state: input.state,
+    codeVerifier: input.codeVerifier,
+    extraParams: GOOGLE_EXTRA_AUTHORIZATION_PARAMS,
   });
 
+const wrapError = <A>(
+  effect: Effect.Effect<A, { readonly message: string }>,
+): Effect.Effect<A, GoogleDiscoveryOAuthError> =>
+  Effect.mapError(effect, (error) => new GoogleDiscoveryOAuthError({ message: error.message }));
+
 export const exchangeAuthorizationCode = (input: {
   readonly clientId: string;
   readonly clientSecret?: string | null;
   readonly redirectUrl: string;
   readonly codeVerifier: string;
   readonly code: string;
 }): Effect.Effect<OAuth2TokenResponse, GoogleDiscoveryOAuthError> =>
-  Effect.gen(function* () {
-    const body = new URLSearchParams({
-      grant_type: "authorization_code",
-      client_id: input.clientId,
-      redirect_uri: input.redirectUrl,
-      code_verifier: input.codeVerifier,
+  wrapError(
+    sharedExchangeAuthorizationCode({
+      tokenUrl: GOOGLE_TOKEN_URL,
+      clientId: input.clientId,
+      clientSecret: input.clientSecret,
+      redirectUrl: input.redirectUrl,
+      codeVerifier: input.codeVerifier,
       code: input.code,
-    });
-    if (input.clientSecret) {
-      body.set("client_secret", input.clientSecret);
-    }
-    return yield* postToTokenEndpoint(body);
-  });
+    }),
+  );
 
 export const refreshAccessToken = (input: {
   readonly clientId: string;
   readonly clientSecret?: string | null;
   readonly refreshToken: string;
   readonly scopes?: readonly string[];
 }): Effect.Effect<OAuth2TokenResponse, GoogleDiscoveryOAuthError> =>
-  Effect.gen(function* () {
-    const body = new URLSearchParams({
-      grant_type: "refresh_token",
-      client_id: input.clientId,
-      refresh_token: input.refreshToken,
-    });
-    if (input.clientSecret) {
-      body.set("client_secret", input.clientSecret);
-    }
-    if (input.scopes && input.scopes.length > 0) {
-      body.set("scope", input.scopes.join(" "));
-    }
-    return yield* postToTokenEndpoint(body);
-  });
+  wrapError(
+    sharedRefreshAccessToken({
+      tokenUrl: GOOGLE_TOKEN_URL,
+      clientId: input.clientId,
+      clientSecret: input.clientSecret,
+      refreshToken: input.refreshToken,
+      scopes: input.scopes,
+    }),
+  );

packages/plugins/google-discovery/src/sdk/oauth.ts

@@ -0,0 +1,49 @@
+{
+  "name": "@executor/plugin-oauth2",
+  "version": "0.0.1",
+  "homepage": "https://github.com/RhysSullivan/executor/tree/main/packages/plugins/oauth2",
+  "bugs": {
+    "url": "https://github.com/RhysSullivan/executor/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RhysSullivan/executor.git",
+    "directory": "packages/plugins/oauth2"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "import": {
+          "types": "./dist/index.d.ts",
+          "default": "./dist/index.js"
+        }
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup && (tsc --declaration --emitDeclarationOnly --outDir dist --rootDir src || true)",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck:slow": "bunx tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "effect": "catalog:"
+  },
+  "devDependencies": {
+    "@effect/vitest": "catalog:",
+    "@types/node": "catalog:",
+    "bun-types": "catalog:",
+    "tsup": "catalog:",
+    "vitest": "catalog:"
+  }
+}