// AK-P16a ยท OAuth state signing for the Google connect flow (CSRF + context). // // The OAuth callback at /integrations/google/oauth/callback is NOT tenant-scoped // (Google redirects to a fixed URI), so the tenant + user travel inside a SIGNED // `state` parameter rather than a cookie. We HMAC-SHA256 the JSON payload with // CRYPTO_SECRET||SESSION_SECRET (same convention as admin-sso/state.server) and // URL-safe-base64 encode it. 10-minute TTL bounds the replay window. import { createHmac, timingSafeEqual } from "node:crypto"; import { loadRequiredWebConfig } from "@hivegrid/config"; const STATE_TTL_MS = 10 * 60 * 1000; const PAYLOAD_VERSION = "v1"; export interface CalendarOAuthStatePayload { readonly tenantId: string; readonly userId: string; readonly tenantSlug: string; /** Epoch milliseconds. */ readonly createdAt: number; } export type VerifyStateResult = | { readonly ok: true; readonly payload: CalendarOAuthStatePayload } | { readonly ok: false; readonly reason: "malformed" | "bad-signature" | "expired" }; function getSecret(override?: string): string { if (override) return override; const { cryptoSecret, sessionSecret } = loadRequiredWebConfig(); const secret = cryptoSecret || sessionSecret; if (!secret) { throw new Error("CRYPTO_SECRET or SESSION_SECRET is required for calendar OAuth state."); } return secret; } function base64UrlEncode(input: string): string { return Buffer.from(input, "utf8").toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""); } function base64UrlDecode(value: string): string { const pad = value.length % 4 === 0 ? "" : "=".repeat(4 - (value.length % 4)); return Buffer.from(value.replace(/-/g, "+").replace(/_/g, "/") + pad, "base64").toString("utf8"); } function sign(body: string, secret: string): string { return Buffer.from(createHmac("sha256", secret).update(body).digest()).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""); } /** Sign a fresh state token for the consent redirect. */ export function signCalendarOAuthState( input: { tenantId: string; userId: string; tenantSlug: string }, options: { now?: () => number; secret?: string } = {}, ): string { const payload: CalendarOAuthStatePayload = { tenantId: input.tenantId, userId: input.userId, tenantSlug: input.tenantSlug, createdAt: options.now ? options.now() : Date.now(), }; const body = base64UrlEncode(JSON.stringify({ v: PAYLOAD_VERSION, p: payload })); return `${body}.${sign(body, getSecret(options.secret))}`; } /** Verify + decode a state token returned by Google. */ export function verifyCalendarOAuthState(state: string, options: { now?: () => number; secret?: string } = {}): VerifyStateResult { const dot = state.lastIndexOf("."); if (dot <= 0) { return { ok: false, reason: "malformed" }; } const body = state.slice(0, dot); const sig = state.slice(dot + 1); let secret: string; try { secret = getSecret(options.secret); } catch { return { ok: false, reason: "malformed" }; } const expected = sign(body, secret); const a = Buffer.from(sig); const b = Buffer.from(expected); if (a.length !== b.length || !timingSafeEqual(a, b)) { return { ok: false, reason: "bad-signature" }; } let decoded: { v: string; p: CalendarOAuthStatePayload }; try { decoded = JSON.parse(base64UrlDecode(body)) as { v: string; p: CalendarOAuthStatePayload }; } catch { return { ok: false, reason: "malformed" }; } if (decoded.v !== PAYLOAD_VERSION || !decoded.p || typeof decoded.p.createdAt !== "number") { return { ok: false, reason: "malformed" }; } const now = options.now ? options.now() : Date.now(); if (now - decoded.p.createdAt > STATE_TTL_MS) { return { ok: false, reason: "expired" }; } return { ok: true, payload: decoded.p }; }