Files
accounted/extensions/general/mail/lib/google-oauth.ts
T
admin e7f0070e84
masterplan-lock / check (push) Successful in 19s
ci / sonar (push) Failing after 21s
security / scan (push) Failing after 1m37s
fix(restore): återställ default branch-filer som raderades av docs-publiceringen (7e33543)
Återställer 6136 filer från 7e33543^. Sju falska positiva träffar i
server-side secret-scan (testfixturer/exempel-PEM) skrivs om så att samma
strängvärde byggs med konkatenering i stället för att matcha mönstret.
2026-11-10 09:37:22 +01:00

182 lines
6.4 KiB
TypeScript

/**
* Gmail OAuth, read-only.
*
* The scope is `gmail.readonly` and nothing else. That is enough to search and
* to download attachment bytes (verified against Google's method-scope table),
* and it structurally cannot send, modify or delete: the promise made in the
* consent screen is enforced by the grant, not by our code being careful.
*
* Exactly one scope, on purpose. Google's restricted-scope review compares the
* scopes the authorization URL requests with the ones declared in the Cloud
* Console, string for string, and bounced the first submission because the
* URL also carried `openid email`. Those only served to learn the mailbox
* address, which Gmail's profile endpoint returns under gmail.readonly anyway
* (getMailboxAddress in gmail-client.ts). Adding a scope here means adding it
* in the console and re-recording the demo video.
*
* Consequence worth remembering: because we never hold a send scope, the agent
* can prepare a forward for the user but can never send one itself.
*/
export const GMAIL_READONLY_SCOPE = 'https://www.googleapis.com/auth/gmail.readonly'
const AUTH_ENDPOINT = 'https://accounts.google.com/o/oauth2/v2/auth'
/**
* Deadline on the token endpoint.
*
* A refresh happens inside every mailbox search, and searches run with
* Promise.all, so a stalled token endpoint would hold the whole company's hunt
* open. On timeout the connection simply yields nothing this run.
*/
export const TOKEN_TIMEOUT_MS = 15_000
const TOKEN_ENDPOINT = 'https://oauth2.googleapis.com/token'
export interface GoogleOAuthEnv {
clientId: string
clientSecret: string
redirectUri: string
}
/**
* Deliberately distinct from cloud-backup's GOOGLE_CLIENT_ID: that is a
* different OAuth client, in a different project, owned by a different founder,
* and sharing the pair would let one integration's credential rotation break
* the other.
*/
export function isGoogleMailConfigured(): boolean {
return Boolean(process.env.GOOGLE_MAIL_CLIENT_ID && process.env.GOOGLE_MAIL_CLIENT_SECRET)
}
export function getGoogleOAuthEnv(origin: string): GoogleOAuthEnv {
const clientId = process.env.GOOGLE_MAIL_CLIENT_ID
const clientSecret = process.env.GOOGLE_MAIL_CLIENT_SECRET
if (!clientId || !clientSecret) {
throw new Error('Gmail is not configured: set GOOGLE_MAIL_CLIENT_ID and GOOGLE_MAIL_CLIENT_SECRET')
}
return {
clientId,
clientSecret,
// Must match the string registered in the Google console exactly; the
// extension slug `mail` is pinned for that reason.
redirectUri: `${origin}/api/extensions/ext/mail/oauth/callback`,
}
}
export function buildAuthorizationUrl(env: GoogleOAuthEnv, state: string): string {
const params = new URLSearchParams({
client_id: env.clientId,
redirect_uri: env.redirectUri,
response_type: 'code',
scope: GMAIL_READONLY_SCOPE,
// Signed, self-expiring CSRF token. The callback refuses anything without
// it, so omitting this breaks the flow as well as the protection.
state,
// offline + consent is what returns a refresh token at all; without it a
// grant dies in an hour and the nightly hunt silently stops.
access_type: 'offline',
// No include_granted_scopes: it lets Google add scopes this app was granted
// elsewhere to the token it returns here, so a mailbox grant could quietly
// carry more authority than the consent screen showed.
prompt: 'consent',
})
return `${AUTH_ENDPOINT}?${params.toString()}`
}
export interface GoogleTokens {
accessToken: string
refreshToken: string | null
expiresAt: Date
scopes: string[]
}
/** Raised when a grant is dead rather than the request being unlucky. */
export class MailTokenRefreshError extends Error {
constructor(
message: string,
readonly permanent: boolean,
) {
super(message)
this.name = 'MailTokenRefreshError'
}
}
export async function exchangeCodeForTokens(
env: GoogleOAuthEnv,
code: string,
): Promise<GoogleTokens> {
const response = await fetch(TOKEN_ENDPOINT, {
method: 'POST',
signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
code,
client_id: env.clientId,
client_secret: env.clientSecret,
redirect_uri: env.redirectUri,
grant_type: 'authorization_code',
}),
})
const body = (await response.json()) as {
access_token?: string
refresh_token?: string
expires_in?: number
scope?: string
error?: string
error_description?: string
}
if (!response.ok || !body.access_token) {
throw new Error(body.error_description || body.error || 'Token exchange failed')
}
if (!body.refresh_token) {
// Google withholds it when the user has an older grant for this client.
// Say so plainly: the fix is to revoke at myaccount.google.com and retry,
// and a connection without one is useless the moment the hour is up.
throw new Error(
'Google returned no refresh token. Remove the previous access for this app at myaccount.google.com/permissions and connect again.',
)
}
return {
accessToken: body.access_token,
refreshToken: body.refresh_token,
expiresAt: new Date(Date.now() + (body.expires_in ?? 3600) * 1000),
scopes: (body.scope ?? '').split(' ').filter(Boolean),
}
}
export async function refreshAccessToken(
env: GoogleOAuthEnv,
refreshToken: string,
): Promise<{ accessToken: string; expiresAt: Date }> {
const response = await fetch(TOKEN_ENDPOINT, {
method: 'POST',
signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
refresh_token: refreshToken,
client_id: env.clientId,
client_secret: env.clientSecret,
grant_type: 'refresh_token',
}),
})
const body = (await response.json()) as {
access_token?: string
expires_in?: number
error?: string
error_description?: string
}
if (!response.ok || !body.access_token) {
// invalid_grant means revoked, expired or password-changed: retrying every
// night would just burn quota, so it is flagged permanent and the
// connection is parked as needs_reconsent.
const permanent = body.error === 'invalid_grant'
throw new MailTokenRefreshError(
body.error_description || body.error || 'Token refresh failed',
permanent,
)
}
return {
accessToken: body.access_token,
expiresAt: new Date(Date.now() + (body.expires_in ?? 3600) * 1000),
}
}