app/lib/google/service-account.server.ts

Functions

Imports

It imports app/lib/timed-fetch.server.ts. Imported by app/lib/google/drive.server.ts, app/lib/google/oauth.server.ts, app/lib/google/refresh.server.ts, app/lib/google/search-console.server.ts, app/lib/health.server.ts, app/routes/auth.google.ts, app/routes/editor.tsx, app/routes/manuscripts.tsx.

Source

1// The Google service account (design decision 6): it reads the manuscripts folder's metadata and
2// Search Console, and cannot do anything else. Two walls: it asks Google only for read-only scopes,
3// and every request it makes passes an allowlist here, so a write through it is refused in code
4// before anything is sent, whatever the scopes would allow.
5
6import { SignJWT } from "jose";
7import { timedFetch } from "~/lib/timed-fetch.server";
8
9/** Read-only, and no drive.readonly: the index takes metadata, and search asks Drive each time. */
10export const SA_SCOPES = ["https://www.googleapis.com/auth/drive.metadata.readonly", "https://www.googleapis.com/auth/webmasters.readonly"];
11
12export const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
13
14export type ServiceAccountKey = { clientEmail: string; privateKey: string; privateKeyId: string; tokenUri: string };
15
16export type SaConnection =
17  | { state: "connected"; key: ServiceAccountKey }
18  | { state: "not-connected"; detail: string }
19  | { state: "misconfigured"; detail: string };
20
21export function saConnection(env: Env): SaConnection {
22  const raw = env.GOOGLE_SA_KEY?.trim();
23  if (!raw) return { state: "not-connected", detail: "GOOGLE_SA_KEY is not set, so the manuscripts index and Search Console are off." };
24  let parsed: Record<string, unknown>;
25  try {
26    parsed = JSON.parse(raw) as Record<string, unknown>;
27  } catch {
28    return { state: "misconfigured", detail: "GOOGLE_SA_KEY is not JSON; set it to the whole key file Google downloads." };
29  }
30  const { type, client_email, private_key, private_key_id, token_uri } = parsed;
31  if (type !== "service_account" || typeof client_email !== "string" || typeof private_key !== "string" || typeof private_key_id !== "string") {
32    return { state: "misconfigured", detail: "GOOGLE_SA_KEY is not a service account key file (type, client_email, private_key, private_key_id)." };
33  }
34  if (!private_key.includes("BEGIN PRIVATE KEY")) return { state: "misconfigured", detail: "GOOGLE_SA_KEY's private_key is not a PKCS#8 PEM key." };
35  // A key file pointing its token endpoint anywhere but Google's would hand the signed assertion elsewhere.
36  const tokenUri = typeof token_uri === "string" ? token_uri : GOOGLE_TOKEN_URL;
37  if (tokenUri !== GOOGLE_TOKEN_URL) return { state: "misconfigured", detail: `GOOGLE_SA_KEY's token_uri is ${tokenUri}, not Google's.` };
38  return { state: "connected", key: { clientEmail: client_email, privateKey: private_key, privateKeyId: private_key_id, tokenUri } };
39}
40
41export class GoogleNotConnected extends Error {
42  constructor(readonly detail: string) {
43    super(detail);
44    this.name = "GoogleNotConnected";
45  }
46}
47
48/** A request the service account is not allowed to make: refused here, never sent. */
49export class ServiceAccountRefused extends Error {
50  constructor(method: string, url: string) {
51    super(`The service account may only read; ${method} ${url} was refused before it was sent.`);
52    this.name = "ServiceAccountRefused";
53  }
54}
55
56// Every request the service account may make: listing files (metadata) and Search Console's query,
57// a POST that reads. Not files.get, whose alt=media returns a file's content.
58const ALLOWED: { method: string; url: RegExp }[] = [
59  { method: "GET", url: /^https:\/\/www\.googleapis\.com\/drive\/v3\/files(\?|$)/ },
60  { method: "POST", url: /^https:\/\/searchconsole\.googleapis\.com\/webmasters\/v3\/sites\/[^/]+\/searchAnalytics\/query$/ },
61];
62
63export function assertReadOnly(method: string, url: string): void {
64  const m = method.toUpperCase();
65  // alt=media asks for content instead of metadata, wherever it appears.
66  const media = new URL(url).searchParams.has("alt") && new URL(url).searchParams.get("alt") !== "json";
67  if (media || !ALLOWED.some((a) => a.method === m && a.url.test(url))) throw new ServiceAccountRefused(m, url);
68}
69
70type Fetch = typeof fetch;
71
72const tokenCache = new Map<string, { token: string; expires: number }>();
73
74export function clearSaTokenCache(): void {
75  tokenCache.clear();
76}
77
78/** A signed JWT exchanged at Google's token endpoint for an hour's access token, cached per key. */
79export async function saAccessToken(key: ServiceAccountKey, fetcher: Fetch = timedFetch, now = Date.now()): Promise<string> {
80  const cached = tokenCache.get(key.privateKeyId);
81  if (cached && cached.expires - 5 * 60_000 > now) return cached.token;
82  const pem = key.privateKey.replace(/-----(BEGIN|END) PRIVATE KEY-----/g, "").replace(/\s+/g, "");
83  const der = Uint8Array.from(atob(pem), (c) => c.charCodeAt(0));
84  const signingKey = await crypto.subtle.importKey("pkcs8", der, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["sign"]);
85  const iat = Math.floor(now / 1000);
86  const assertion = await new SignJWT({ scope: SA_SCOPES.join(" ") })
87    .setProtectedHeader({ alg: "RS256", kid: key.privateKeyId, typ: "JWT" })
88    .setIssuer(key.clientEmail)
89    .setAudience(key.tokenUri)
90    .setIssuedAt(iat)
91    .setExpirationTime(iat + 3600)
92    .sign(signingKey);
93  const res = await fetcher(key.tokenUri, {
94    method: "POST",
95    headers: { "Content-Type": "application/x-www-form-urlencoded" },
96    body: new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion }).toString(),
97  });
98  if (!res.ok) {
99    const body = (await res.json().catch(() => ({}))) as { error?: string; error_description?: string };
100    // invalid_grant is how Google answers a deleted, disabled or expired key.
101    throw new Error(`Google refused the service account key (${res.status} ${body.error ?? ""}${body.error_description ? `: ${body.error_description}` : ""}).`);
102  }
103  const body = (await res.json()) as { access_token: string; expires_in: number };
104  tokenCache.set(key.privateKeyId, { token: body.access_token, expires: now + body.expires_in * 1000 });
105  return body.access_token;
106}
107
108/** The service account's only way to reach Google: read-only by allowlist, then authenticated. */
109export function saClient(env: Env, fetcher: Fetch = timedFetch) {
110  const connection = saConnection(env);
111  if (connection.state !== "connected") throw new GoogleNotConnected(connection.detail);
112  return {
113    key: connection.key,
114    async request(method: string, url: string, body?: unknown): Promise<Response> {
115      assertReadOnly(method, url);
116      const token = await saAccessToken(connection.key, fetcher);
117      return fetcher(url, {
118        method,
119        headers: { Authorization: `Bearer ${token}`, ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
120        body: body === undefined ? undefined : JSON.stringify(body),
121      });
122    },
123  };
124}