@bygghammar/cms-platform 0.90.0-m7.9 → 0.91.0

package/src/server/google-service-account.ts

@@ -0,0 +1,325 @@
+/**
+ * Google service-account authentication.
+ *
+ * A service account is the only Google credential this platform accepts: the
+ * editor shares a private spreadsheet with the account's email address and
+ * nothing has to be published to the web. The key itself lives in the server
+ * environment exactly like every other provider credential (see
+ * `provider-secrets.ts`) — never in PostgreSQL, never in page content, never in
+ * anything sent to a browser.
+ *
+ * Signing is done with the platform's Web Crypto API, so there is no new
+ * dependency and nothing Google-specific to install.
+ */
+
+import type { Env } from "./provider-secrets";
+
+/** Environment variables that hold the credential. */
+export const GOOGLE_SA_EMAIL_ENV = "GOOGLE_SERVICE_ACCOUNT_EMAIL";
+export const GOOGLE_SA_KEY_ENV = "GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY";
+/** Optional single-variable form: the whole downloaded JSON key file. */
+export const GOOGLE_SA_JSON_ENV = "GOOGLE_SERVICE_ACCOUNT_JSON";
+
+export const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+
+/** Read/write access to the spreadsheets the account has been shared on. */
+export const SHEETS_SCOPE = "https://www.googleapis.com/auth/spreadsheets";
+
+/**
+ * Read-only access to file *metadata* — enough to ask Drive whether this
+ * account may edit a file, and not enough to read one byte of its contents.
+ *
+ * Only the connection test asks for it. Appends stay on {@link SHEETS_SCOPE}
+ * alone, so the credential that runs on every submission carries no Drive
+ * access at all.
+ */
+export const DRIVE_METADATA_SCOPE = "https://www.googleapis.com/auth/drive.metadata.readonly";
+
+/** The two scopes the connection test asks for, in one token. */
+export const SHEETS_TEST_SCOPE = `${SHEETS_SCOPE} ${DRIVE_METADATA_SCOPE}`;
+
+export type GoogleCredentials = {
+  clientEmail: string;
+  /** PKCS#8 PEM. Never logged, never returned to a client. */
+  privateKey: string;
+};
+
+/** Why a Google call could not even be attempted. */
+export type GoogleAuthErrorCode = "credentials-missing" | "credentials-invalid" | "api-unavailable";
+
+export class GoogleAuthError extends Error {
+  readonly code: GoogleAuthErrorCode;
+  constructor(code: GoogleAuthErrorCode, message: string) {
+    super(message);
+    this.name = "GoogleAuthError";
+    this.code = code;
+  }
+}
+
+/** Accept both real newlines and the `\n` escapes used inside .env files. */
+function normalizePrivateKey(raw: string): string {
+  return raw
+    .trim()
+    .replace(/^"(.*)"$/s, "$1")
+    .replace(/^'(.*)'$/s, "$1")
+    .replace(/\\r/g, "")
+    .replace(/\\n/g, "\n")
+    .trim();
+}
+
+function fromJsonKeyFile(raw: string | undefined): GoogleCredentials | null {
+  if (!raw?.trim()) return null;
+  let text = raw.trim();
+  // Some deployments paste the key file base64-encoded to dodge newline rules.
+  if (!text.startsWith("{")) {
+    try {
+      text = atob(text);
+    } catch {
+      return null;
+    }
+  }
+  try {
+    const parsed = JSON.parse(text) as Record<string, unknown>;
+    const email = typeof parsed["client_email"] === "string" ? parsed["client_email"] : "";
+    const key = typeof parsed["private_key"] === "string" ? parsed["private_key"] : "";
+    if (!email || !key) return null;
+    return { clientEmail: email.trim(), privateKey: normalizePrivateKey(key) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the configured service account, or `null` when the server has none.
+ *
+ * The JSON key file wins when both forms are present: it is the artefact Google
+ * hands out, so a deployment that pastes it verbatim should not be silently
+ * overridden by a half-filled pair of variables.
+ */
+export function resolveGoogleCredentials(env: Env = process.env): GoogleCredentials | null {
+  const fromJson = fromJsonKeyFile(env[GOOGLE_SA_JSON_ENV]);
+  if (fromJson) return fromJson;
+
+  const email = env[GOOGLE_SA_EMAIL_ENV]?.trim();
+  const key = env[GOOGLE_SA_KEY_ENV];
+  if (!email || !key?.trim()) return null;
+  return { clientEmail: email, privateKey: normalizePrivateKey(key) };
+}
+
+/**
+ * The address an editor has to share a spreadsheet with. Safe to show in the
+ * backoffice and to put in an error message — it is an identifier, not a
+ * secret, and it is the one thing an editor cannot guess.
+ */
+export function googleServiceAccountEmail(env: Env = process.env): string | null {
+  return resolveGoogleCredentials(env)?.clientEmail ?? null;
+}
+
+/** True when the server can talk to Google at all. */
+export function hasGoogleServiceAccount(env: Env = process.env): boolean {
+  return resolveGoogleCredentials(env) !== null;
+}
+
+function base64Url(bytes: ArrayBuffer | Uint8Array): string {
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let binary = "";
+  for (const byte of view) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function base64UrlText(value: string): string {
+  return base64Url(new TextEncoder().encode(value));
+}
+
+/** PEM → DER. Throws `credentials-invalid` rather than leaking the key text. */
+function pemToDer(pem: string): Uint8Array {
+  const match = /-----BEGIN (?:RSA )?PRIVATE KEY-----([\s\S]+?)-----END (?:RSA )?PRIVATE KEY-----/.exec(
+    pem,
+  );
+  if (!match) {
+    throw new GoogleAuthError(
+      "credentials-invalid",
+      `${GOOGLE_SA_KEY_ENV} is not a PEM private key. Paste the "private_key" value from the service account's JSON key file, newlines included.`,
+    );
+  }
+  const body = match[1]!.replace(/\s+/g, "");
+  let binary: string;
+  try {
+    binary = atob(body);
+  } catch {
+    throw new GoogleAuthError("credentials-invalid", `${GOOGLE_SA_KEY_ENV} is not valid base64.`);
+  }
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
+async function signJwt(credentials: GoogleCredentials, scope: string): Promise<string> {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new GoogleAuthError(
+      "api-unavailable",
+      "This server has no Web Crypto implementation, so a Google request cannot be signed.",
+    );
+  }
+  const now = Math.floor(Date.now() / 1000);
+  const header = base64UrlText(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const claim = base64UrlText(
+    JSON.stringify({
+      iss: credentials.clientEmail,
+      scope,
+      aud: GOOGLE_TOKEN_URL,
+      iat: now,
+      exp: now + 3600,
+    }),
+  );
+  const input = `${header}.${claim}`;
+
+  let key: CryptoKey;
+  try {
+    const der = pemToDer(credentials.privateKey);
+    key = await subtle.importKey(
+      "pkcs8",
+      der.buffer.slice(der.byteOffset, der.byteOffset + der.byteLength) as ArrayBuffer,
+      { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+      false,
+      ["sign"],
+    );
+  } catch (err) {
+    if (err instanceof GoogleAuthError) throw err;
+    throw new GoogleAuthError(
+      "credentials-invalid",
+      `${GOOGLE_SA_KEY_ENV} could not be read as an RSA private key. Copy it again from the service account's JSON key file.`,
+    );
+  }
+
+  const signature = await subtle.sign(
+    "RSASSA-PKCS1-v1_5",
+    key,
+    new TextEncoder().encode(input) as unknown as ArrayBuffer,
+  );
+  return `${input}.${base64Url(signature)}`;
+}
+
+type CachedToken = { token: string; expiresAt: number };
+
+/**
+ * Access tokens last an hour; minting one costs an RSA signature and a round
+ * trip, so a busy form does not pay for it on every submission.
+ */
+const tokenCache = new Map<string, CachedToken>();
+
+/** Test seam — drop cached tokens so a credential change takes effect. */
+export function clearGoogleTokenCache(): void {
+  tokenCache.clear();
+}
+
+export type GoogleFetch = typeof fetch;
+
+/**
+ * How long any single outbound Google call may take.
+ *
+ * A visitor submitting a form waits on this. Without a deadline, a connection
+ * Google accepts and then never answers holds the submission open until some
+ * proxy further out gives up — the visitor watches a spinner, and the server
+ * holds the socket. Ten seconds is well past a healthy Sheets append and well
+ * short of anybody's patience.
+ */
+export const GOOGLE_REQUEST_TIMEOUT_MS = 10_000;
+
+/** A fresh deadline for one outbound Google request. */
+export function googleRequestSignal(ms: number = GOOGLE_REQUEST_TIMEOUT_MS): AbortSignal {
+  return AbortSignal.timeout(ms);
+}
+
+/**
+ * Exchange the service account's signed JWT for an OAuth access token.
+ *
+ * Errors carry a code and a message safe to show an administrator: they name
+ * the environment variable or the HTTP status, never the key or the token.
+ */
+export async function googleAccessToken(
+  credentials: GoogleCredentials,
+  scope: string = SHEETS_SCOPE,
+  fetchImpl: GoogleFetch = fetch,
+): Promise<string> {
+  const cacheKey = `${credentials.clientEmail}|${scope}`;
+  const cached = tokenCache.get(cacheKey);
+  // 60s of slack so a token cannot expire between here and the API call.
+  if (cached && cached.expiresAt - 60_000 > Date.now()) return cached.token;
+
+  const assertion = await signJwt(credentials, scope);
+  let res: Response;
+  try {
+    res = await fetchImpl(GOOGLE_TOKEN_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+        assertion,
+      }).toString(),
+      signal: googleRequestSignal(),
+    });
+  } catch {
+    throw new GoogleAuthError(
+      "api-unavailable",
+      "Google could not be reached. Check the server's outbound network access and try again.",
+    );
+  }
+
+  if (!res.ok) {
+    const detail = await googleErrorDetail(res);
+    if (res.status >= 500) {
+      throw new GoogleAuthError(
+        "api-unavailable",
+        `Google's token service is unavailable (HTTP ${res.status}). Try again shortly.`,
+      );
+    }
+    throw new GoogleAuthError(
+      "credentials-invalid",
+      `Google rejected the service account credentials${detail ? ` (${detail})` : ""}. Check ${GOOGLE_SA_EMAIL_ENV} and ${GOOGLE_SA_KEY_ENV}.`,
+    );
+  }
+
+  const body = (await res.json().catch(() => null)) as {
+    access_token?: unknown;
+    expires_in?: unknown;
+  } | null;
+  const token = typeof body?.access_token === "string" ? body.access_token : "";
+  if (!token) {
+    throw new GoogleAuthError(
+      "credentials-invalid",
+      "Google returned no access token for the service account.",
+    );
+  }
+  const ttl = typeof body?.expires_in === "number" ? body.expires_in : 3600;
+  tokenCache.set(cacheKey, { token, expiresAt: Date.now() + ttl * 1000 });
+  return token;
+}
+
+/**
+ * Short, safe description of a Google error response.
+ *
+ * Google echoes the request in some errors, so only the documented status text
+ * is used and it is truncated — nothing here can grow into a credential dump.
+ */
+export async function googleErrorDetail(res: Response): Promise<string> {
+  const text = await res.text().catch(() => "");
+  if (!text) return "";
+  try {
+    const parsed = JSON.parse(text) as {
+      error?: unknown;
+      error_description?: unknown;
+    };
+    const err = parsed.error;
+    if (err && typeof err === "object" && "message" in err) {
+      const message = (err as { message?: unknown }).message;
+      if (typeof message === "string") return message.slice(0, 200);
+    }
+    if (typeof parsed.error_description === "string") return parsed.error_description.slice(0, 200);
+    if (typeof err === "string") return err.slice(0, 200);
+  } catch {
+    /* fall through to the truncated raw body */
+  }
+  return text.slice(0, 200);
+}