diff --git a/README.md b/README.md index 1680e0636..0fb0ae237 100644 --- a/README.md +++ b/README.md @@ -986,6 +986,35 @@ Google ID tokens are RS256-signed JWTs. The discovery document advertises RS256, Google authentication is permissive by default for local bearer-token workflows. Set `google.strict_scopes: true` in seed config to require emulator-issued, unexpired access tokens on Gmail, Calendar, Drive, and userinfo routes. Invalid credentials return `401 UNAUTHENTICATED`; missing method scopes return `403` with `insufficientPermissions`. Strict mode distinguishes read, write, send, settings, and metadata scopes, and userinfo includes only granted identity claims. Revoking an access or refresh token invalidates the linked access and refresh credentials. Discovery, signing keys, and the sign-in page remain public. This mode checks method scopes; resource-specific grants such as `drive.file` and Gmail add-on scopes are not modeled. +When OAuth clients are configured, `POST /oauth2/token` takes the client's credentials as `client_id` and `client_secret` in the body (`client_secret_post`) or in an HTTP Basic `Authorization` header (`client_secret_basic`), for both the authorization code and refresh token grants. Body credentials sent with the header must repeat it: a different `client_id` or `client_secret`, or a `client_secret` without `client_id`, returns `400 invalid_request`. As Google does, the emulator compares the Basic username and password as sent, without form-decoding them. + +`messages.send` and `drafts.send` deliver the message to each `To`, `Cc`, and `Bcc` recipient who is a user of the emulator. Before delivery, `From` must be a single mailbox whose address is one of the sender's send-as addresses (`GET .../settings/sendAs`). Otherwise it is replaced with their default send-as address. Either way, the message fields and the raw MIME `From` are rebuilt from the checked name and address. The recipient gets a copy labeled `INBOX` and `UNREAD`, without the `Bcc` header, threaded with the messages it replies to in their mailbox, and with their filters applied. Recipients who aren't emulator users are skipped. A message sent to yourself stays one message, labeled `SENT`, `INBOX`, and `UNREAD`, unless your own filters remove those labels. `messages.insert` and `messages.import` don't deliver. + +`POST /oauth2/token` accepts the JWT bearer grant (`grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`) for service accounts seeded under `google.service_accounts`. Each key takes the `key_id` from the account's key file and its PEM public key or X.509 certificate, so the private key stays with the code under test. + +```yaml +google: + users: + - email: alice@example.com + service_accounts: + - client_email: archiver@my-project.iam.gserviceaccount.com + client_id: "104523180291234567890" + keys: + - key_id: 5f0c2b7e9a + public_key: | + -----BEGIN PUBLIC KEY----- + ... + -----END PUBLIC KEY----- + domain_wide_delegation: + - client_id: "104523180291234567890" + scopes: + - https://www.googleapis.com/auth/gmail.readonly +``` + +The assertion must be RS256-signed by one of the account's keys, with `iss` set to the account's `client_email`, a space-delimited `scope`, `aud` set to `https://oauth2.googleapis.com/token` or the emulator's own `/oauth2/token` URL, and an `exp` at most 65 minutes after `iat`. A `kid` that names none of the account's keys falls back to trying every key. The response has `access_token`, `expires_in: 3600`, `scope`, and `token_type: Bearer`, and no refresh token. Without `sub`, the token acts as the service account, including under `google.strict_scopes`. With `sub`, it acts as that user, and every requested scope must be granted to the account's `client_id` under `google.domain_wide_delegation`. Under `google.strict_scopes`, Gmail, Calendar, and Drive check the token's scopes as they do for other tokens. + +Errors follow Google's JWT error table: `invalid_scope` for an empty `scope`, `invalid_grant` for an unknown `sub` user, an unknown account, a bad signature, a wrong audience, or an expired or too-long-lived assertion, `401 unauthorized_client` when the account has no delegation or none of the requested scopes are delegated, and `403 access_denied` when only some of them are. The other errors return `400`. User suspension, key expiry, and `target_audience` ID tokens are not modeled. + - `GET /o/oauth2/v2/auth` - authorization endpoint - `POST /oauth2/token` - token exchange - `GET /oauth2/v2/userinfo` - get user info diff --git a/apps/web/content/docs/google.mdx b/apps/web/content/docs/google.mdx index 5be77cf18..f66253180 100644 --- a/apps/web/content/docs/google.mdx +++ b/apps/web/content/docs/google.mdx @@ -17,6 +17,35 @@ Google ID tokens are RS256-signed JWTs. The discovery document advertises RS256, Google authentication is permissive by default for local bearer-token workflows. Set `google.strict_scopes: true` in seed config to require emulator-issued, unexpired access tokens on Gmail, Calendar, Drive, and userinfo routes. Invalid credentials return `401 UNAUTHENTICATED`; missing method scopes return `403` with `insufficientPermissions`. Strict mode distinguishes read, write, send, settings, and metadata scopes, and userinfo includes only granted identity claims. Revoking an access or refresh token invalidates the linked access and refresh credentials. Discovery, signing keys, and the sign-in page remain public. This mode checks method scopes; resource-specific grants such as `drive.file` and Gmail add-on scopes are not modeled. +When OAuth clients are configured, `POST /oauth2/token` takes the client's credentials as `client_id` and `client_secret` in the body (`client_secret_post`) or in an HTTP Basic `Authorization` header (`client_secret_basic`), for both the authorization code and refresh token grants. Body credentials sent with the header must repeat it: a different `client_id` or `client_secret`, or a `client_secret` without `client_id`, returns `400 invalid_request`. As Google does, the emulator compares the Basic username and password as sent, without form-decoding them. + +## Service Accounts + +`POST /oauth2/token` accepts the JWT bearer grant (`grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`) for service accounts seeded under `google.service_accounts`. Each key takes the `key_id` from the account's key file and its PEM public key or X.509 certificate, so the private key stays with the code under test. + +```yaml +google: + users: + - email: alice@example.com + service_accounts: + - client_email: archiver@my-project.iam.gserviceaccount.com + client_id: "104523180291234567890" + keys: + - key_id: 5f0c2b7e9a + public_key: | + -----BEGIN PUBLIC KEY----- + ... + -----END PUBLIC KEY----- + domain_wide_delegation: + - client_id: "104523180291234567890" + scopes: + - https://www.googleapis.com/auth/gmail.readonly +``` + +The assertion must be RS256-signed by one of the account's keys, with `iss` set to the account's `client_email`, a space-delimited `scope`, `aud` set to `https://oauth2.googleapis.com/token` or the emulator's own `/oauth2/token` URL, and an `exp` at most 65 minutes after `iat`. A `kid` that names none of the account's keys falls back to trying every key. The response has `access_token`, `expires_in: 3600`, `scope`, and `token_type: Bearer`, and no refresh token. Without `sub`, the token acts as the service account, including under `google.strict_scopes`. With `sub`, it acts as that user, and every requested scope must be granted to the account's `client_id` under `google.domain_wide_delegation`. Under `google.strict_scopes`, Gmail, Calendar, and Drive check the token's scopes as they do for other tokens. + +Errors follow Google's JWT error table: `invalid_scope` for an empty `scope`, `invalid_grant` for an unknown `sub` user, an unknown account, a bad signature, a wrong audience, or an expired or too-long-lived assertion, `401 unauthorized_client` when the account has no delegation or none of the requested scopes are delegated, and `403 access_denied` when only some of them are. The other errors return `400`. User suspension, key expiry, and `target_audience` ID tokens are not modeled. + ## Gmail - `GET /gmail/v1/users/:userId/messages` - list messages (`q`, `labelIds`, `maxResults`, `pageToken`) @@ -30,6 +59,8 @@ Google authentication is permissive by default for local bearer-token workflows. - `POST /gmail/v1/users/:userId/messages/:id/trash` - trash message - `POST /gmail/v1/users/:userId/messages/:id/untrash` - untrash message +`messages.send` and `drafts.send` deliver the message to each `To`, `Cc`, and `Bcc` recipient who is a user of the emulator. Before delivery, `From` must be a single mailbox whose address is one of the sender's send-as addresses (`GET .../settings/sendAs`). Otherwise it is replaced with their default send-as address. Either way, the message fields and the raw MIME `From` are rebuilt from the checked name and address. The recipient gets a copy labeled `INBOX` and `UNREAD`, without the `Bcc` header, threaded with the messages it replies to in their mailbox, and with their filters applied. Recipients who aren't emulator users are skipped. A message sent to yourself stays one message, labeled `SENT`, `INBOX`, and `UNREAD`, unless your own filters remove those labels. `messages.insert` and `messages.import` don't deliver. + ## Gmail Drafts - `GET /gmail/v1/users/:userId/drafts` - list drafts diff --git a/apps/web/tests/fixtures/docs-baseline.json b/apps/web/tests/fixtures/docs-baseline.json index 77a42333c..9ae2d72c0 100644 --- a/apps/web/tests/fixtures/docs-baseline.json +++ b/apps/web/tests/fixtures/docs-baseline.json @@ -167,6 +167,7 @@ "ogTitle": "Google API | emulate", "headings": [ "OAuth & OpenID Connect", + "Service Accounts", "Gmail", "Gmail Drafts", "Gmail Threads", diff --git a/packages/@emulators/google/README.md b/packages/@emulators/google/README.md index 1ca1a33bd..13dad3408 100644 --- a/packages/@emulators/google/README.md +++ b/packages/@emulators/google/README.md @@ -19,6 +19,35 @@ npm install @emulators/google - `GET /.well-known/openid-configuration` — OIDC discovery document - `GET /oauth2/v3/certs` — JSON Web Key Set (JWKS) with the RSA public key for ID token verification +When OAuth clients are configured, `POST /oauth2/token` takes the client's credentials as `client_id` and `client_secret` in the body (`client_secret_post`) or in an HTTP Basic `Authorization` header (`client_secret_basic`), for both the authorization code and refresh token grants. Body credentials sent with the header must repeat it: a different `client_id` or `client_secret`, or a `client_secret` without `client_id`, returns `400 invalid_request`. As Google does, the emulator compares the Basic username and password as sent, without form-decoding them. + +### Service accounts + +`POST /oauth2/token` accepts the JWT bearer grant (`grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`) for service accounts seeded under `google.service_accounts`. Each key takes the `key_id` from the account's key file and its PEM public key or X.509 certificate, so the private key stays with the code under test. + +```yaml +google: + users: + - email: alice@example.com + service_accounts: + - client_email: archiver@my-project.iam.gserviceaccount.com + client_id: "104523180291234567890" + keys: + - key_id: 5f0c2b7e9a + public_key: | + -----BEGIN PUBLIC KEY----- + ... + -----END PUBLIC KEY----- + domain_wide_delegation: + - client_id: "104523180291234567890" + scopes: + - https://www.googleapis.com/auth/gmail.readonly +``` + +The assertion must be RS256-signed by one of the account's keys, with `iss` set to the account's `client_email`, a space-delimited `scope`, `aud` set to `https://oauth2.googleapis.com/token` or the emulator's own `/oauth2/token` URL, and an `exp` at most 65 minutes after `iat`. A `kid` that names none of the account's keys falls back to trying every key. The response has `access_token`, `expires_in: 3600`, `scope`, and `token_type: Bearer`, and no refresh token. Without `sub`, the token acts as the service account, including under `google.strict_scopes`. With `sub`, it acts as that user, and every requested scope must be granted to the account's `client_id` under `google.domain_wide_delegation`. Under `google.strict_scopes`, Gmail, Calendar, and Drive check the token's scopes as they do for other tokens. + +Errors follow Google's JWT error table: `invalid_scope` for an empty `scope`, `invalid_grant` for an unknown `sub` user, an unknown account, a bad signature, a wrong audience, or an expired or too-long-lived assertion, `401 unauthorized_client` when the account has no delegation or none of the requested scopes are delegated, and `403 access_denied` when only some of them are. The other errors return `400`. User suspension, key expiry, and `target_audience` ID tokens are not modeled. + ### Gmail - `GET /gmail/v1/users/:userId/messages` — list messages with `q`, `labelIds`, `maxResults`, and `pageToken` - `GET /gmail/v1/users/:userId/messages/:id` — fetch message in `full`, `metadata`, `minimal`, or `raw` formats @@ -31,6 +60,8 @@ npm install @emulators/google - `POST /gmail/v1/users/:userId/messages/:id/trash` — trash message - `POST /gmail/v1/users/:userId/messages/:id/untrash` — untrash message +`messages.send` and `drafts.send` deliver the message to each `To`, `Cc`, and `Bcc` recipient who is a user of the emulator. Before delivery, `From` must be a single mailbox whose address is one of the sender's send-as addresses (`GET .../settings/sendAs`). Otherwise it is replaced with their default send-as address. Either way, the message fields and the raw MIME `From` are rebuilt from the checked name and address. The recipient gets a copy labeled `INBOX` and `UNREAD`, without the `Bcc` header, threaded with the messages it replies to in their mailbox, and with their filters applied. Recipients who aren't emulator users are skipped. A message sent to yourself stays one message, labeled `SENT`, `INBOX`, and `UNREAD`, unless your own filters remove those labels. `messages.insert` and `messages.import` don't deliver. + ### Drafts - `GET /gmail/v1/users/:userId/drafts` — list drafts - `POST /gmail/v1/users/:userId/drafts` — create draft diff --git a/packages/@emulators/google/src/__tests__/gmail-delivery.test.ts b/packages/@emulators/google/src/__tests__/gmail-delivery.test.ts new file mode 100644 index 000000000..a68ebc72b --- /dev/null +++ b/packages/@emulators/google/src/__tests__/gmail-delivery.test.ts @@ -0,0 +1,293 @@ +import { describe, expect, it } from "vitest"; +import { Hono, Store, WebhookDispatcher, authMiddleware, type AppEnv, type TokenMap } from "@emulators/core"; +import { googlePlugin, seedFromConfig } from "../index.js"; +import { buildRawMessage } from "../helpers.js"; + +const base = "http://localhost:4000"; +const users = { alice: "alice@example.com", bob: "bob@example.com", carol: "carol@example.com" }; + +interface MessageResource { + id: string; + threadId: string; + labelIds: string[]; + raw?: string; + payload?: { headers: Array<{ name: string; value: string }> }; +} + +function fixture() { + const app = new Hono(); + const store = new Store(); + const tokens: TokenMap = new Map(); + for (const [name, email] of Object.entries(users)) tokens.set(`${name}-token`, { login: email, id: 1, scopes: [] }); + app.use("*", authMiddleware(tokens)); + googlePlugin.register(app, store, new WebhookDispatcher(), base, tokens); + googlePlugin.seed?.(store, base); + seedFromConfig(store, base, { users: Object.values(users).map((email) => ({ email })) }); + + async function call(user: keyof typeof users, method: string, path: string, body?: unknown) { + const res = await app.request(`${base}/gmail/v1/users/me${path}`, { + method, + headers: { Authorization: `Bearer ${user}-token`, "Content-Type": "application/json" }, + ...(body === undefined ? {} : { body: JSON.stringify(body) }), + }); + expect(res.status, `${method} ${path}`).toBe(200); + return res.json() as Promise; + } + + async function inbox(user: keyof typeof users): Promise { + const list = (await call(user, "GET", "/messages?labelIds=INBOX")) as { messages?: Array<{ id: string }> }; + return Promise.all((list.messages ?? []).map((m) => call(user, "GET", `/messages/${m.id}`))); + } + + const header = (message: MessageResource, name: string) => + message.payload?.headers.find((entry) => entry.name.toLowerCase() === name.toLowerCase())?.value; + + return { call, inbox, header }; +} + +function raw(fields: Parameters[0]): string { + return buildRawMessage(fields); +} + +describe("Gmail delivery of sent messages", () => { + it("delivers messages.send to To, Cc, and Bcc users as unread inbox mail without the Bcc header", async () => { + const { call, inbox, header } = fixture(); + const sent = (await call("alice", "POST", "/messages/send", { + raw: raw({ + from: users.alice, + to: `Bob <${users.bob}>, outside@elsewhere.test`, + bcc: `"Carol, via Bcc" <${users.carol.toUpperCase()}>`, + subject: "Quarterly numbers", + body_text: "Attached below.", + }), + })) as MessageResource; + expect(sent.labelIds).toEqual(["SENT"]); + + const [bobCopy] = await inbox("bob"); + const [carolCopy] = await inbox("carol"); + for (const copy of [bobCopy, carolCopy]) { + expect(copy.id).not.toBe(sent.id); + expect(copy.labelIds.sort()).toEqual(["INBOX", "UNREAD"]); + expect(header(copy, "Subject")).toBe("Quarterly numbers"); + expect(header(copy, "Bcc")).toBeUndefined(); + const rawCopy = (await call(copy === bobCopy ? "bob" : "carol", "GET", `/messages/${copy.id}?format=raw`)) as { + raw: string; + }; + expect(Buffer.from(rawCopy.raw, "base64url").toString("utf8")).not.toMatch(/^bcc:/im); + } + expect(await inbox("alice")).toEqual([]); + + // The sender's copy keeps its Bcc header. + const sentFull = (await call("alice", "GET", `/messages/${sent.id}`)) as MessageResource; + expect(header(sentFull, "Bcc")).toContain(users.carol.toUpperCase()); + }); + + it("delivers structured sends and drafts.send, and threads replies in the recipient's mailbox", async () => { + const { call, inbox, header } = fixture(); + const first = (await call("alice", "POST", "/messages/send", { + to: users.bob, + subject: "Lunch?", + body_text: "Noon works.", + })) as MessageResource; + const [received] = await inbox("bob"); + expect(header(received, "Subject")).toBe("Lunch?"); + const messageId = header(received, "Message-ID")!; + expect(messageId).toBe( + header((await call("alice", "GET", `/messages/${first.id}`)) as MessageResource, "Message-ID"), + ); + + const draft = (await call("bob", "POST", "/drafts", { + message: { + raw: raw({ + from: users.bob, + to: users.alice, + subject: "Re: Lunch?", + body_text: "See you then.", + in_reply_to: messageId, + references: messageId, + }), + }, + })) as { id: string }; + const reply = (await call("bob", "POST", "/drafts/send", { id: draft.id })) as MessageResource; + expect(reply.threadId).toBe(received.threadId); + expect(reply.labelIds).toEqual(["SENT"]); + + const [aliceCopy] = await inbox("alice"); + expect(aliceCopy.labelIds.sort()).toEqual(["INBOX", "UNREAD"]); + expect(aliceCopy.threadId).toBe(first.threadId); + const thread = (await call("alice", "GET", `/threads/${first.threadId}`)) as { messages: MessageResource[] }; + expect(thread.messages).toHaveLength(2); + }); + + it("replaces a From address the sender can't send as with their default address", async () => { + const { call, inbox, header } = fixture(); + const decoded = async (user: keyof typeof users, id: string) => + Buffer.from( + ((await call(user, "GET", `/messages/${id}?format=raw`)) as { raw: string }).raw, + "base64url", + ).toString("utf8"); + + const viaRaw = (await call("alice", "POST", "/messages/send", { + raw: raw({ from: `Bob <${users.bob}>`, to: users.carol, subject: "Raw", body_text: "Hi." }), + })) as MessageResource; + await call("alice", "POST", "/messages/send", { from: users.bob, to: users.carol, subject: "Fields" }); + const draft = (await call("alice", "POST", "/drafts", { + message: { raw: raw({ from: users.bob, to: users.carol, subject: "Draft", body_text: "Hi." }) }, + })) as { id: string }; + await call("alice", "POST", "/drafts/send", { id: draft.id }); + + const copies = await inbox("carol"); + expect(copies.map((copy) => header(copy, "Subject")).sort()).toEqual(["Draft", "Fields", "Raw"]); + for (const copy of copies) { + expect(header(copy, "From")).toBe(`alice <${users.alice}>`); + const source = await decoded("carol", copy.id); + expect(source).toMatch(/^From: alice \r?$/m); + expect(source).not.toContain(users.bob); + } + expect(header((await call("alice", "GET", `/messages/${viaRaw.id}`)) as MessageResource, "From")).toBe( + `alice <${users.alice}>`, + ); + expect(await decoded("alice", viaRaw.id)).not.toContain(users.bob); + + // An address the sender owns is kept as written. + await call("alice", "POST", "/messages/send", { from: `Alice A `, to: users.bob }); + const [bobCopy] = await inbox("bob"); + expect(header(bobCopy, "From")).toBe("Alice A "); + }); + + it("parses From as a mailbox list before checking it against send-as addresses", async () => { + const { call, inbox, header } = fixture(); + const cases = [ + // A quoted local part, which an address scan drops, leaving only the sender's own address. + [`"bob"@example.com, ${users.alice}`, `alice <${users.alice}>`], + // A quote inside a comment, which a scan that strips quoted strings first reads the wrong way round. + [`(") bob@example.com (") ${users.alice}`, `alice <${users.alice}>`], + // A nested comment around another address is only a comment, and is dropped when From is rebuilt. + [`${users.alice} (see (also) bob@example.com)`, users.alice], + [`"Alice, A." <${users.alice}>`, `"Alice, A." <${users.alice}>`], + ]; + for (const [from, expected] of cases) { + await call("alice", "POST", "/messages/send", { from, to: users.carol, subject: `fields ${from}` }); + await call("alice", "POST", "/messages/send", { + raw: raw({ from, to: users.carol, subject: `raw ${from}`, body_text: "Hi." }), + }); + const draft = (await call("alice", "POST", "/drafts", { + message: { raw: raw({ from, to: users.carol, subject: `draft ${from}`, body_text: "Hi." }) }, + })) as { id: string }; + await call("alice", "POST", "/drafts/send", { id: draft.id }); + for (const kind of ["fields", "raw", "draft"]) { + const copy = (await inbox("carol")).find((message) => header(message, "Subject") === `${kind} ${from}`)!; + expect(header(copy, "From"), `${kind} ${from}`).toBe(expected); + const source = Buffer.from( + ((await call("carol", "GET", `/messages/${copy.id}?format=raw`)) as { raw: string }).raw, + "base64url", + ).toString("utf8"); + expect(source.match(/^From:.*$/gim), `${kind} ${from}`).toEqual([`From: ${expected}`]); + } + } + }); + + it("rewrites a malformed From without stalling", async () => { + const { call, inbox, header } = fixture(); + const from = `${users.bob})`; + const started = Date.now(); + await call("alice", "POST", "/messages/send", { from, to: users.carol, subject: "fields malformed" }); + await call("alice", "POST", "/messages/send", { + raw: raw({ from, to: users.carol, subject: "raw malformed", body_text: "Hi." }), + }); + const draft = (await call("alice", "POST", "/drafts", { + message: { raw: raw({ from, to: users.carol, subject: "draft malformed", body_text: "Hi." }) }, + })) as { id: string }; + await call("alice", "POST", "/drafts/send", { id: draft.id }); + const elapsed = Date.now() - started; + + const copies = await inbox("carol"); + expect(copies.map((copy) => header(copy, "Subject")).sort()).toEqual([ + "draft malformed", + "fields malformed", + "raw malformed", + ]); + for (const copy of copies) { + expect(header(copy, "From")).toBe(`alice <${users.alice}>`); + const source = Buffer.from( + ((await call("carol", "GET", `/messages/${copy.id}?format=raw`)) as { raw: string }).raw, + "base64url", + ).toString("utf8"); + expect(source.match(/^From:.*$/gim)).toEqual([`From: alice <${users.alice}>`]); + } + expect(elapsed).toBeLessThan(1000); + }); + + it("labels a message sent to oneself SENT, INBOX, and UNREAD without a second copy", async () => { + const { call, inbox } = fixture(); + const sent = (await call("alice", "POST", "/messages/send", { + to: users.alice, + cc: users.alice, + subject: "Note to self", + body_text: "Buy milk.", + })) as MessageResource; + expect(sent.labelIds.sort()).toEqual(["INBOX", "SENT", "UNREAD"]); + const delivered = await inbox("alice"); + expect(delivered.map((message) => message.id)).toEqual([sent.id]); + }); + + it("applies the recipient's filters to the delivered copy", async () => { + const { call, inbox } = fixture(); + await call("bob", "POST", "/settings/filters", { + criteria: { from: users.alice }, + action: { removeLabelIds: ["INBOX", "UNREAD"] }, + }); + await call("alice", "POST", "/messages/send", { to: users.bob, subject: "FYI", body_text: "No action." }); + expect(await inbox("bob")).toEqual([]); + const all = (await call("bob", "GET", "/messages")) as { messages: Array<{ id: string }> }; + expect(all.messages).toHaveLength(1); + }); + + it("applies the sender's filters to a message sent to oneself", async () => { + const { call, inbox } = fixture(); + await call("alice", "POST", "/settings/filters", { + criteria: { from: users.alice }, + action: { removeLabelIds: ["INBOX", "UNREAD"] }, + }); + const sent = (await call("alice", "POST", "/messages/send", { + to: users.alice, + subject: "Note to self", + body_text: "Archived on arrival.", + })) as MessageResource; + expect(sent.labelIds).toEqual(["SENT"]); + expect(await inbox("alice")).toEqual([]); + }); + + it("removes a folded Bcc header and keeps the body of a raw MIME message", async () => { + const { call, inbox } = fixture(); + const mime = [ + `From: ${users.alice}`, + `To: ${users.bob}`, + "Subject: Folded", + `Bcc: someone@elsewhere.test,`, + ` ${users.carol}`, + "", + "Body line one", + "", + "Body line two", + ].join("\r\n"); + await call("alice", "POST", "/messages/send", { raw: Buffer.from(mime).toString("base64url") }); + for (const user of ["bob", "carol"] as const) { + const [copy] = await inbox(user); + const rawCopy = (await call(user, "GET", `/messages/${copy.id}?format=raw`)) as { raw: string }; + expect(Buffer.from(rawCopy.raw, "base64url").toString("utf8")).toBe( + [`From: ${users.alice}`, `To: ${users.bob}`, "Subject: Folded", "", "Body line one", "", "Body line two"].join( + "\r\n", + ), + ); + } + }); + + it("does not deliver inserted or imported messages", async () => { + const { call, inbox } = fixture(); + const message = { raw: raw({ from: users.alice, to: users.bob, subject: "Archived", body_text: "Old mail." }) }; + await call("alice", "POST", "/messages", message); + await call("alice", "POST", "/messages/import", message); + expect(await inbox("bob")).toEqual([]); + }); +}); diff --git a/packages/@emulators/google/src/__tests__/service-accounts.test.ts b/packages/@emulators/google/src/__tests__/service-accounts.test.ts new file mode 100644 index 000000000..a5d476871 --- /dev/null +++ b/packages/@emulators/google/src/__tests__/service-accounts.test.ts @@ -0,0 +1,260 @@ +import { generateKeyPairSync, type KeyObject } from "node:crypto"; +import { describe, expect, it } from "vitest"; +import { SignJWT } from "jose"; +import { Hono, Store, WebhookDispatcher, authMiddleware, type AppEnv, type TokenMap } from "@emulators/core"; +import { googlePlugin, seedFromConfig, type GoogleSeedConfig } from "../index.js"; + +const base = "http://localhost:4000"; +const tokenUrl = "https://oauth2.googleapis.com/token"; +const gmailReadonly = "https://www.googleapis.com/auth/gmail.readonly"; +const gmailSend = "https://www.googleapis.com/auth/gmail.send"; +const calendar = "https://www.googleapis.com/auth/calendar"; +const serviceAccount = "archiver@emulate-project.iam.gserviceaccount.com"; +const clientId = "104523180291234567890"; + +// A certificate only, from a throwaway key pair whose private key was discarded. +const certificate = [ + "-----BEGIN CERTIFICATE-----", + "MIIDLzCCAhegAwIBAgIUbX/vBrxXw8DC79AUKjg6SV8zILYwDQYJKoZIhvcNAQEL", + "BQAwJzElMCMGA1UEAwwcZW11bGF0ZS10ZXN0LXNlcnZpY2UtYWNjb3VudDAeFw0y", + "NjExMTQwMTEwNDBaFw0zNjExMTEwMTEwNDBaMCcxJTAjBgNVBAMMHGVtdWxhdGUt", + "dGVzdC1zZXJ2aWNlLWFjY291bnQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK", + "AoIBAQCei2FE/D0EeiIRkmFi1X9wuKoo/w/XX7TBd2QpjFPZPXN5H86Ty/8cGjHg", + "K02sgA+S+Ba8xYc6lNp+mJ0RpIk2T5A+QRNmDEN0OuYu1wDT6mEMW2JXAvzNxZw6", + "opXNt9rBOVmLH6xXs0wn/oflli3U5ux0tloaF9JiY6eufha0FqUcxQHmXpCvDbtv", + "D6uO2rZw1XxDXG0wbrD/oDf0xectTvX5rdOaSwRHEdlGt2pZSNyVp2LTA7753fJr", + "9CxZb+63R5fw+c0aJtasyOYt4hABx209Zg9CmEXrlGcIYa65QdGh4JMN/awQtbzh", + "t/EaoqC1HaiK/e7vhahbWnguteCbAgMBAAGjUzBRMB0GA1UdDgQWBBSPuZspfLhg", + "HMGYW6isov1s6wTo4DAfBgNVHSMEGDAWgBSPuZspfLhgHMGYW6isov1s6wTo4DAP", + "BgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQB4g48WQirU7ZAOeppA", + "RRrmSVdSsWZBj6gcNHhAJxQjZ8XGFwNHn2/uZ8utrFVy4ECOYxr9AWw3dcXaIuVr", + "Q6+uJ1k8FELszKHhLrjKhzIuPpEVbwEVdfsWKdDRKvg9K7YnsXgqBUwQB41lqTP/", + "XhFWwvkwO7MKVmRnZgSL8zCgOhlDfUFUBNlhHr7UTJJJfsY9LP0nXAekgf4dZ3U+", + "KS2A5nUvk7lQ7ltnUVZRX6pk0/BP+F/2oH3EmtVYzAoBCOh6ucqlfij8RjxjGzkz", + "ZLlpKiqo/pnN5XMlXbm0uGy/N0jrm7DhylaATpmrIMKmgtFQTFq5xkl1MSOqK/Cb", + "+tkt", + "-----END CERTIFICATE-----", +].join("\n"); + +function keyPair() { + return generateKeyPairSync("rsa", { modulusLength: 2048 }); +} + +const signing = keyPair(); +const rotated = keyPair(); + +function fixture(overrides: Partial = {}) { + const app = new Hono(); + const store = new Store(); + const tokens: TokenMap = new Map(); + app.use("*", authMiddleware(tokens)); + googlePlugin.register(app, store, new WebhookDispatcher(), base, tokens); + googlePlugin.seed?.(store, base); + seedFromConfig(store, base, { + strict_scopes: true, + users: [{ email: "alice@example.com" }], + messages: [ + { + id: "msg", + user_email: "alice@example.com", + from: "bob@example.com", + to: "alice@example.com", + body_text: "Hi", + label_ids: ["INBOX"], + }, + ], + service_accounts: [ + { + client_email: serviceAccount, + client_id: clientId, + keys: [ + { key_id: "old-key", public_key: rotated.publicKey.export({ type: "spki", format: "pem" }).toString() }, + { key_id: "current-key", public_key: signing.publicKey.export({ type: "spki", format: "pem" }).toString() }, + ], + }, + ], + domain_wide_delegation: [{ client_id: clientId, scopes: [gmailReadonly, gmailSend] }], + ...overrides, + }); + + async function exchange(assertion: string) { + const res = await app.request(`${base}/oauth2/token`, { + 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(), + }); + return { status: res.status, json: (await res.json()) as Record }; + } + + const get = (path: string, token: string) => + app.request(`${base}${path}`, { headers: { Authorization: `Bearer ${token}` } }); + const gmail = (token: string) => get("/gmail/v1/users/me/messages", token); + + return { exchange, gmail, get }; +} + +async function assertion( + claims: Record = {}, + options: { key?: KeyObject; kid?: string; alg?: string } = {}, +): Promise { + const now = Math.floor(Date.now() / 1000); + return new SignJWT({ iss: serviceAccount, scope: gmailReadonly, aud: tokenUrl, iat: now, exp: now + 3600, ...claims }) + .setProtectedHeader({ alg: options.alg ?? "RS256", typ: "JWT", kid: options.kid ?? "current-key" }) + .sign(options.key ?? signing.privateKey); +} + +const shortLived = + "Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your iat and exp values in the JWT claim."; + +describe("Google service account tokens", () => { + it("issues a one-hour token without a refresh token that acts as the delegated user", async () => { + const { exchange, gmail } = fixture(); + const res = await exchange(await assertion({ sub: "alice@example.com" })); + expect(res.status).toBe(200); + expect(res.json).toEqual({ + access_token: expect.stringMatching(/^google_/), + expires_in: 3600, + scope: gmailReadonly, + token_type: "Bearer", + }); + + const list = await gmail(res.json.access_token); + expect(list.status).toBe(200); + expect(((await list.json()) as { messages: Array<{ id: string }> }).messages.map((m) => m.id)).toEqual(["msg"]); + }); + + it("limits a delegated token to its requested scopes under strict_scopes", async () => { + const { exchange, gmail } = fixture(); + const res = await exchange(await assertion({ sub: "alice@example.com", scope: gmailSend })); + expect(res.status).toBe(200); + expect((await gmail(res.json.access_token)).status).toBe(403); + }); + + it("issues a token for the service account itself without sub", async () => { + const { exchange } = fixture({ domain_wide_delegation: [] }); + const res = await exchange(await assertion({ scope: `${gmailReadonly} ${calendar}` })); + expect(res.status).toBe(200); + expect(res.json.scope).toBe(`${gmailReadonly} ${calendar}`); + }); + + it("lets a token without sub call the APIs as the service account under strict_scopes", async () => { + const { exchange, get } = fixture({ domain_wide_delegation: [] }); + const drive = await exchange(await assertion({ scope: "https://www.googleapis.com/auth/drive" })); + expect(drive.status).toBe(200); + const files = await get("/drive/v3/files", drive.json.access_token); + expect(files.status).toBe(200); + expect(((await files.json()) as { files: unknown[] }).files).toEqual([]); + + // Scopes are still checked, and an unknown bearer token is still refused. + expect((await get("/drive/v3/files", (await exchange(await assertion())).json.access_token)).status).toBe(403); + expect((await get("/drive/v3/files", "google_unknown")).status).toBe(401); + }); + + it("accepts the emulator's own token URL as the audience", async () => { + const { exchange } = fixture(); + expect((await exchange(await assertion({ aud: `${base}/oauth2/token` }))).status).toBe(200); + expect( + (await exchange(await assertion({ aud: "http://localhost:4001/oauth2/token" }))).json.error_description, + ).toBe("Invalid JWT: Invalid audience."); + }); + + it("tries every key when the key ID is wrong or missing", async () => { + const { exchange } = fixture(); + expect((await exchange(await assertion({}, { kid: "unknown-key" }))).status).toBe(200); + expect((await exchange(await assertion({}, { kid: "old-key" }))).status).toBe(200); + expect((await exchange(await assertion({}, { key: rotated.privateKey, kid: "current-key" }))).status).toBe(200); + }); + + it("returns Google's errors for bad assertions", async () => { + const { exchange } = fixture(); + const now = Math.floor(Date.now() / 1000); + const other = keyPair(); + const cases: Array<[string, Record]> = [ + ["not-a-jwt", { error: "invalid_request", error_description: "Bad Request" }], + [ + await assertion({ scope: "" }), + { error: "invalid_scope", error_description: "Invalid OAuth scope or ID token audience provided." }, + ], + [ + await assertion({ sub: "nobody@example.com" }), + { error: "invalid_grant", error_description: "Not a valid email or user ID." }, + ], + [ + await assertion({ iss: "unknown@emulate-project.iam.gserviceaccount.com" }), + { error: "invalid_grant", error_description: "Invalid grant: account not found" }, + ], + [ + await assertion({}, { key: other.privateKey }), + { error: "invalid_grant", error_description: "Invalid JWT Signature." }, + ], + [ + await assertion({}, { key: other.privateKey, alg: "RS384" }), + { error: "invalid_grant", error_description: "Invalid JWT Signature." }, + ], + [ + await assertion({ aud: "https://example.com/token" }), + { error: "invalid_grant", error_description: "Invalid JWT: Invalid audience." }, + ], + [await assertion({ iat: now, exp: now + 66 * 60 }), { error: "invalid_grant", error_description: shortLived }], + [await assertion({ iat: now, exp: now - 60 }), { error: "invalid_grant", error_description: shortLived }], + [ + await assertion({ iat: now - 2 * 3600, exp: now - 3600 }), + { error: "invalid_grant", error_description: shortLived }, + ], + ]; + for (const [jwt, expected] of cases) { + const res = await exchange(jwt); + expect(res.status, JSON.stringify(expected)).toBe(400); + expect(res.json).toEqual(expected); + } + }); + + it("accepts the older token URLs as the audience", async () => { + const { exchange } = fixture(); + for (const aud of ["https://accounts.google.com/o/oauth2/token", "https://www.googleapis.com/oauth2/v4/token"]) { + expect((await exchange(await assertion({ aud }))).status, aud).toBe(200); + } + }); + + it("refuses delegation the Admin console has not granted", async () => { + const noDelegation = fixture({ domain_wide_delegation: [] }); + expect(await noDelegation.exchange(await assertion({ sub: "alice@example.com" }))).toEqual({ + status: 401, + json: { error: "unauthorized_client", error_description: "Unauthorized client or scope in request." }, + }); + + const { exchange } = fixture(); + expect(await exchange(await assertion({ sub: "alice@example.com", scope: calendar }))).toEqual({ + status: 401, + json: { + error: "unauthorized_client", + error_description: + "Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested.", + }, + }); + expect( + await exchange(await assertion({ sub: "alice@example.com", scope: `${gmailReadonly} ${calendar}` })), + ).toEqual({ + status: 403, + json: { error: "access_denied", error_description: "Requested client not authorized." }, + }); + }); + + it("accepts an X.509 certificate as a key and rejects keys that are not PEM", async () => { + const { exchange } = fixture({ + service_accounts: [ + { client_email: serviceAccount, client_id: clientId, keys: [{ key_id: "cert", public_key: certificate }] }, + ], + }); + // The signing key is not the certificate's, so the account exists but the signature fails. + expect((await exchange(await assertion())).json.error_description).toBe("Invalid JWT Signature."); + + expect(() => + fixture({ + service_accounts: [ + { client_email: serviceAccount, client_id: clientId, keys: [{ key_id: "x", public_key: "nope" }] }, + ], + }), + ).toThrow(/not a PEM public key or certificate/); + }); +}); diff --git a/packages/@emulators/google/src/__tests__/token-basic-auth.test.ts b/packages/@emulators/google/src/__tests__/token-basic-auth.test.ts new file mode 100644 index 000000000..b3cfb774d --- /dev/null +++ b/packages/@emulators/google/src/__tests__/token-basic-auth.test.ts @@ -0,0 +1,178 @@ +import { describe, expect, it } from "vitest"; +import { Hono, Store, WebhookDispatcher, authMiddleware, type AppEnv, type TokenMap } from "@emulators/core"; +import { googlePlugin, seedFromConfig } from "../index.js"; + +const base = "http://localhost:4000"; +const redirectUri = "http://localhost/callback"; +const client = { client_id: "basic-client.apps.googleusercontent.com", client_secret: "basic-secret" }; + +function basic(username: string, password: string): string { + return `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`; +} + +function fixture(options: { strict?: boolean; clients?: boolean } = {}) { + const app = new Hono(); + const store = new Store(); + const tokens: TokenMap = new Map(); + app.use("*", authMiddleware(tokens)); + googlePlugin.register(app, store, new WebhookDispatcher(), base, tokens); + googlePlugin.seed?.(store, base); + seedFromConfig(store, base, { + ...(options.strict === undefined ? {} : { strict_scopes: options.strict }), + users: [{ email: "alice@example.com", name: "Alice Example" }], + ...(options.clients === false ? {} : { oauth_clients: [{ ...client, redirect_uris: [redirectUri] }] }), + }); + + async function code(): Promise { + const res = await app.request(`${base}/o/oauth2/v2/auth/callback`, { + method: "POST", + headers: { "Content-Type": "application/x-www-form-urlencoded" }, + body: new URLSearchParams({ + email: "alice@example.com", + redirect_uri: redirectUri, + scope: "openid email", + client_id: client.client_id, + }).toString(), + }); + return new URL(res.headers.get("Location")!).searchParams.get("code")!; + } + + async function token(body: Record, authorization?: string) { + const res = await app.request(`${base}/oauth2/token`, { + method: "POST", + headers: { + "Content-Type": "application/x-www-form-urlencoded", + ...(authorization ? { Authorization: authorization } : {}), + }, + body: new URLSearchParams(body).toString(), + }); + return { status: res.status, headers: res.headers, json: (await res.json()) as Record }; + } + + return { code, token }; +} + +const mismatch = { + error: "invalid_request", + error_description: "Credentials in post body and basic Authorization header do not match", +}; + +describe("Google token endpoint client_secret_basic", () => { + for (const strict of [false, true]) { + it(`exchanges a code and a refresh token with Basic credentials (strict_scopes ${strict})`, async () => { + const { code, token } = fixture({ strict }); + const header = basic(client.client_id, client.client_secret); + const exchanged = await token( + { grant_type: "authorization_code", code: await code(), redirect_uri: redirectUri }, + header, + ); + expect(exchanged.status).toBe(200); + expect(exchanged.json.access_token).toBeTruthy(); + + const refreshed = await token( + { grant_type: "refresh_token", refresh_token: exchanged.json.refresh_token }, + header, + ); + expect(refreshed.status).toBe(200); + expect(refreshed.json.access_token).toBeTruthy(); + }); + } + + it("accepts body credentials that repeat the header's", async () => { + const { code, token } = fixture(); + const header = basic(client.client_id, client.client_secret); + const grant = { grant_type: "authorization_code", redirect_uri: redirectUri }; + const extras: Array> = [ + { ...client }, + { client_id: client.client_id }, + { client_id: client.client_id, client_secret: "" }, + ]; + for (const extra of extras) { + const res = await token({ ...grant, code: await code(), ...extra }, header); + expect(res.status, JSON.stringify(extra)).toBe(200); + } + }); + + it("refuses body credentials that differ from the header's", async () => { + const { code, token } = fixture(); + const header = basic(client.client_id, client.client_secret); + const grant = { grant_type: "authorization_code", redirect_uri: redirectUri, code: await code() }; + const extras: Array> = [ + { client_id: "other-client" }, + { client_id: client.client_id, client_secret: "other-secret" }, + // A body secret needs its client_id, even when it equals the header's secret. + { client_secret: client.client_secret }, + ]; + for (const extra of extras) { + const res = await token({ ...grant, ...extra }, header); + expect(res.status, JSON.stringify(extra)).toBe(400); + expect(res.json).toEqual(mismatch); + } + // The code was not used up by the refused requests. + expect((await token(grant, header)).status).toBe(200); + }); + + it("compares Basic credentials as sent, without form-decoding them", async () => { + const { code, token } = fixture(); + const grant = { grant_type: "authorization_code", redirect_uri: redirectUri, code: await code() }; + const encodedId = client.client_id.replace(/\./g, "%2E"); + expect( + (await token({ ...grant, client_id: client.client_id }, basic(encodedId, client.client_secret))).json, + ).toEqual(mismatch); + const unknown = await token(grant, basic(encodedId, client.client_secret)); + expect(unknown.status).toBe(401); + expect(unknown.json.error).toBe("invalid_client"); + }); + + it("returns invalid_client for a wrong header secret or client, without WWW-Authenticate", async () => { + const { code, token } = fixture(); + const grant = { grant_type: "authorization_code", redirect_uri: redirectUri, code: await code() }; + const wrongSecret = await token(grant, basic(client.client_id, "wrong")); + expect(wrongSecret.status).toBe(401); + expect(wrongSecret.json).toEqual({ error: "invalid_client", error_description: "The client_secret is incorrect." }); + expect(wrongSecret.headers.get("WWW-Authenticate")).toBeNull(); + + const wrongClient = await token(grant, basic("other-client", client.client_secret)); + expect(wrongClient.status).toBe(401); + expect(wrongClient.json.error).toBe("invalid_client"); + }); + + it("returns invalid_request for a malformed header or an empty client ID", async () => { + const { code, token } = fixture(); + const grant = { grant_type: "authorization_code", redirect_uri: redirectUri, code: await code() }; + const malformed = await token(grant, `Basic ${Buffer.from("no-colon").toString("base64")}`); + expect(malformed.status).toBe(400); + expect(malformed.json).toEqual({ error: "invalid_request", error_description: "Bad Request" }); + + const empty = await token(grant, basic("", client.client_secret)); + expect(empty.status).toBe(400); + expect(empty.json).toEqual({ + error: "invalid_request", + error_description: "Could not determine client ID from request.", + }); + }); + + it("refreshes a token from a body-credential exchange with Basic credentials", async () => { + const { code, token } = fixture(); + const exchanged = await token({ + grant_type: "authorization_code", + code: await code(), + redirect_uri: redirectUri, + ...client, + }); + const res = await token( + { grant_type: "refresh_token", refresh_token: exchanged.json.refresh_token }, + basic(client.client_id, client.client_secret), + ); + expect(res.status).toBe(200); + }); + + it("ignores client credentials when no OAuth clients are configured", async () => { + const { code, token } = fixture({ clients: false }); + const res = await token( + { grant_type: "authorization_code", code: await code(), redirect_uri: redirectUri, client_id: "anything" }, + basic("other", "secret"), + ); + expect(res.status).toBe(200); + }); +}); diff --git a/packages/@emulators/google/src/auth.ts b/packages/@emulators/google/src/auth.ts index 4bad0db41..df0a07602 100644 --- a/packages/@emulators/google/src/auth.ts +++ b/packages/@emulators/google/src/auth.ts @@ -1,6 +1,7 @@ import type { AppEnv, Hono, MiddlewareHandler, Store } from "@emulators/core"; import { googleApiError } from "./helpers.js"; import { getAccessTokens } from "./oauth-tokens.js"; +import { findServiceAccount } from "./service-accounts.js"; import { getGoogleStore } from "./store.js"; const googleScopes = (...names: string[]) => names.map((name) => `https://www.googleapis.com/auth/${name}`); @@ -102,7 +103,10 @@ export function googleAuthMiddleware(app: Hono, store: Store): Middlewar const token = c.req.header("Authorization")?.match(/^Bearer\s+(\S+)\s*$/i)?.[1]; const record = token ? getAccessTokens(store).get(token) : undefined; - const user = record && getGoogleStore(store).users.findOneBy("email", record.email); + // Service account tokens without sub act as the account itself, which is not a user of the emulator. + const user = + record && + (getGoogleStore(store).users.findOneBy("email", record.email) ?? findServiceAccount(store, record.email)); if (!token || !record || record.expiresAt <= Date.now() || !user) { return googleApiError(c, 401, "Request had invalid authentication credentials.", "authError", "UNAUTHENTICATED"); } diff --git a/packages/@emulators/google/src/helpers.ts b/packages/@emulators/google/src/helpers.ts index 79b3f7026..fb190b025 100644 --- a/packages/@emulators/google/src/helpers.ts +++ b/packages/@emulators/google/src/helpers.ts @@ -704,7 +704,259 @@ export function sendDraftMessage(gs: GoogleStore, draft: GoogleDraft): GoogleMes message.label_ids.filter((labelId) => labelId !== "DRAFT").concat("SENT"), ); clearDraftRecordsForMessage(gs, message.user_email, message.gmail_id); - return sent; + return deliverSentMessage(gs, sent); +} + +/** + * Delivers a sent message to the To, Cc, and Bcc recipients who are users of the emulator. Each + * recipient gets a copy labeled INBOX and UNREAD, with the Bcc header removed. A message the sender + * sends to themselves stays one message and gains INBOX and UNREAD. A From address that isn't one of + * the sender's send-as addresses is first replaced with their default one. Returns the sender's message. + */ +export function deliverSentMessage(gs: GoogleStore, message: GoogleMessage): GoogleMessage { + const sent = applySendAsFrom(gs, message); + const sender = sent.user_email.toLowerCase(); + const recipients = new Set( + [sent.to, sent.cc, sent.bcc].flatMap((header) => (header ? parseAddressList(header) : [])), + ); + let result = sent; + const raw = sent.raw ? removeRawHeader(sent.raw, "bcc") : null; + + for (const address of recipients) { + const user = gs.users.all().find((candidate) => candidate.email.toLowerCase() === address); + if (!user) continue; + if (address === sender) { + // The sender's filters act on the incoming side too, so one that skips the inbox or marks read still applies. + const incoming = applyFiltersToLabelIds(gs, user.email, sent.from, [...result.label_ids, "INBOX", "UNREAD"]); + result = markMessageModified(gs, result, incoming); + continue; + } + createStoredMessage(gs, { + user_email: user.email, + raw: raw ?? undefined, + from: sent.from, + to: sent.to, + cc: sent.cc, + bcc: null, + reply_to: sent.reply_to, + subject: sent.subject, + body_text: sent.body_text, + body_html: sent.body_html, + message_id: sent.message_id, + references: sent.references, + in_reply_to: sent.in_reply_to, + internal_date: sent.internal_date, + label_ids: ["INBOX", "UNREAD"], + }); + } + return result; +} + +/** + * Gmail sends only from the account's send-as addresses + * (https://developers.google.com/workspace/gmail/api/guides/alias_and_signature_settings), so a token for one user + * can't put another address in From. The From is parsed as an RFC 5322 mailbox list, and it must hold exactly one + * mailbox whose address is a send-as address. Either way, the stored field and the raw MIME header are both rebuilt + * from the identity that was checked: the parsed name and address, or the default send-as address when the check fails. + */ +function applySendAsFrom(gs: GoogleStore, message: GoogleMessage): GoogleMessage { + const aliases = listSendAsForUser(gs, message.user_email); + const authorized = (header: string): string | null => { + const mailboxes = parseMailboxList(header); + if (mailboxes?.length !== 1) return null; + const [{ name, address }] = mailboxes; + if (!aliases.some((alias) => alias.send_as_email.toLowerCase() === address.toLowerCase())) return null; + return formatMailbox(name || null, address); + }; + // messages.send fills the stored From with the caller's address, so a raw message's own From header is checked too. + const rawFrom = message.raw ? parseRawMessage(message.raw).from : ""; + const fieldFrom = authorized(message.from); + let from = rawFrom ? authorized(rawFrom) : fieldFrom; + if (from === null || fieldFrom === null) { + const primary = aliases.find((alias) => alias.is_default) ?? aliases[0]!; + from = formatMailbox(primary.display_name, primary.send_as_email); + } + const raw = message.raw ? setRawHeader(message.raw, "from", from) : null; + if (from === message.from && raw === message.raw) return message; + return gs.messages.update(message.id, { from, raw }) ?? message; +} + +function formatMailbox(name: string | null, address: string): string { + const display = name?.replace(/[\r\n]+/g, " ").trim(); + if (!display) return address; + if (/^(=\?[^?\s]+\?[BbQq]\?[^?\s]*\?=\s*)+$/.test(display)) return `${display} <${address}>`; + if (/[^\x20-\x7e]/.test(display)) { + return `=?UTF-8?B?${Buffer.from(display, "utf8").toString("base64")}?= <${address}>`; + } + if (/^[\w .'-]+$/.test(display)) return `${display} <${address}>`; + return `"${display.replace(/["\\]/g, "\\$&")}" <${address}>`; +} + +interface Mailbox { + name: string; + address: string; +} + +type HeaderToken = { kind: "atom" | "quoted" | "literal" | "special"; value: string }; + +const HEADER_SPECIALS = "<>@,;:.\\]"; +const ATOM_STOP = ` \t()"[${HEADER_SPECIALS}`; + +/** + * Parses an RFC 5322 mailbox list (section 3.4) such as `"Doe, Jane" , bob@example.com`, handling + * quoted strings, nested comments, and domain literals. Returns null for anything it can't read unambiguously, + * including groups, so callers treat it as invalid rather than guess. + */ +function parseMailboxList(header: string): Mailbox[] | null { + const text = header.replace(/\r?\n(?=[ \t])/g, ""); + const tokens: HeaderToken[] = []; + let i = 0; + while (i < text.length) { + const char = text[i]!; + if (char === " " || char === "\t") { + i++; + } else if (char === "(") { + let depth = 0; + for (; i < text.length; i++) { + if (text[i] === "\\") i++; + else if (text[i] === "(") depth++; + else if (text[i] === ")" && --depth === 0) break; + } + if (depth !== 0) return null; + i++; + } else if (char === '"') { + let value = ""; + for (i++; i < text.length && text[i] !== '"'; i++) { + if (text[i] === "\\") i++; + if (i < text.length) value += text[i]; + } + if (i >= text.length) return null; + tokens.push({ kind: "quoted", value }); + i++; + } else if (char === "[") { + const end = text.indexOf("]", i); + if (end === -1) return null; + tokens.push({ kind: "literal", value: text.slice(i, end + 1) }); + i = end + 1; + } else if (char === ")") { + // A closing parenthesis outside a comment is malformed. + return null; + } else if (HEADER_SPECIALS.includes(char)) { + tokens.push({ kind: "special", value: char }); + i++; + } else { + let end = i; + while (end < text.length && !ATOM_STOP.includes(text[end]!)) end++; + // Every character that stops an atom has a branch above. Don't spin if one is ever added without one. + if (end === i) return null; + tokens.push({ kind: "atom", value: text.slice(i, end) }); + i = end; + } + } + + const mailboxes: Mailbox[] = []; + let current: HeaderToken[] = []; + for (const token of [...tokens, { kind: "special", value: "," } as HeaderToken]) { + if (token.kind !== "special" || token.value !== ",") { + current.push(token); + continue; + } + const mailbox = parseMailbox(current); + if (!mailbox) return null; + mailboxes.push(mailbox); + current = []; + } + return mailboxes; +} + +function isSpecial(token: HeaderToken | undefined, value: string): boolean { + return token?.kind === "special" && token.value === value; +} + +function parseMailbox(tokens: HeaderToken[]): Mailbox | null { + const open = tokens.findIndex((token) => isSpecial(token, "<")); + if (open === -1) { + const address = parseAddrSpec(tokens); + return address ? { name: "", address } : null; + } + if (!isSpecial(tokens[tokens.length - 1], ">")) return null; + const phrase = tokens.slice(0, open); + if (phrase.some((token) => token.kind !== "atom" && token.kind !== "quoted" && !isSpecial(token, "."))) return null; + const address = parseAddrSpec(tokens.slice(open + 1, -1)); + return address ? { name: phrase.map((token) => token.value).join(" "), address } : null; +} + +/** Reads `local@domain`, keeping a quoted local part quoted so it can't match an unquoted address. */ +function parseAddrSpec(tokens: HeaderToken[]): string | null { + const at = tokens.findIndex((token) => isSpecial(token, "@")); + if (at <= 0) return null; + const local = joinDotted(tokens.slice(0, at), true); + const domainTokens = tokens.slice(at + 1); + const domain = + domainTokens.length === 1 && domainTokens[0]!.kind === "literal" + ? domainTokens[0]!.value + : joinDotted(domainTokens, false); + return local && domain ? `${local}@${domain}` : null; +} + +function joinDotted(tokens: HeaderToken[], allowQuoted: boolean): string | null { + if (tokens.length % 2 === 0) return null; + const parts: string[] = []; + for (const [index, token] of tokens.entries()) { + if (index % 2 === 1) { + if (!isSpecial(token, ".")) return null; + } else if (token.kind === "atom") { + parts.push(token.value); + } else if (token.kind === "quoted" && allowQuoted) { + parts.push(`"${token.value.replace(/["\\]/g, "\\$&")}"`); + } else { + return null; + } + } + return parts.join("."); +} + +/** Lowercased addresses in an address-list header such as `Bob , carol@example.com`. */ +function parseAddressList(header: string): string[] { + const withoutNames = header.replace(/"(?:[^"\\]|\\.)*"/g, "").replace(/\([^)]*\)/g, ""); + return (withoutNames.match(/[^\s<>,;:]+@[^\s<>,;]+/g) ?? []).map((address) => address.toLowerCase()); +} + +/** Removes a header, with its folded continuation lines, from a base64url MIME message. */ +function removeRawHeader(raw: string, name: string): string { + return setRawHeader(raw, name, null); +} + +/** + * Replaces every occurrence of a header, with its folded continuation lines, in a base64url MIME message by one + * line carrying `value`, or removes them when `value` is null. A header that isn't there is added first. + */ +function setRawHeader(raw: string, name: string, value: string | null): string { + const source = decodeBase64Like(raw).toString("latin1"); + const match = /\r?\n\r?\n/.exec(source); + const headerEnd = match ? match.index : source.length; + const lines = source.slice(0, headerEnd).split(/(?<=\n)/); + const eol = lines[0]?.endsWith("\r\n") || !lines[0]?.endsWith("\n") ? "\r\n" : "\n"; + const replacement = value === null ? null : `${name.replace(/^./, (c) => c.toUpperCase())}: ${value}${eol}`; + const kept: string[] = []; + let skipping = false; + let replaced = false; + for (const line of lines) { + if (/^[ \t]/.test(line)) { + if (!skipping) kept.push(line); + continue; + } + skipping = line.slice(0, line.indexOf(":")).trim().toLowerCase() === name; + if (!skipping) kept.push(line); + else if (replacement && !replaced) { + kept.push(replacement); + replaced = true; + } + } + if (replacement && !replaced) kept.unshift(replacement); + // The header block ends without a line break, so drop the one a removed or replaced last header leaves behind. + const headers = kept.join("").replace(/\r?\n$/, ""); + return Buffer.from(headers + source.slice(headerEnd), "latin1").toString("base64url"); } export function deleteDraftMessage(gs: GoogleStore, draft: GoogleDraft): boolean { diff --git a/packages/@emulators/google/src/index.ts b/packages/@emulators/google/src/index.ts index f2c479802..832612592 100644 --- a/packages/@emulators/google/src/index.ts +++ b/packages/@emulators/google/src/index.ts @@ -21,9 +21,11 @@ import { settingsRoutes } from "./routes/settings.js"; import { threadRoutes } from "./routes/threads.js"; import { getGoogleStore } from "./store.js"; import { googleAuthMiddleware } from "./auth.js"; +import { seedServiceAccounts, type GoogleSeedDelegation, type GoogleSeedServiceAccount } from "./service-accounts.js"; export { getGoogleStore, type GoogleStore } from "./store.js"; export * from "./entities.js"; +export type { GoogleSeedDelegation, GoogleSeedServiceAccount } from "./service-accounts.js"; export interface GoogleSeedUser { email: string; @@ -128,6 +130,8 @@ export interface GoogleSeedConfig { calendars?: GoogleSeedCalendar[]; calendar_events?: GoogleSeedCalendarEvent[]; drive_items?: GoogleSeedDriveItem[]; + service_accounts?: GoogleSeedServiceAccount[]; + domain_wide_delegation?: GoogleSeedDelegation[]; } function seedDefaults(store: Store, _baseUrl: string): void { @@ -321,6 +325,8 @@ export function seedFromConfig(store: Store, _baseUrl: string, config: GoogleSee } } + seedServiceAccounts(store, config.service_accounts, config.domain_wide_delegation); + if (config.oauth_clients) { for (const client of config.oauth_clients) { const existing = gs.oauthClients.findOneBy("client_id", client.client_id); diff --git a/packages/@emulators/google/src/oauth-tokens.ts b/packages/@emulators/google/src/oauth-tokens.ts index a82bb9047..05cd08d0b 100644 --- a/packages/@emulators/google/src/oauth-tokens.ts +++ b/packages/@emulators/google/src/oauth-tokens.ts @@ -36,7 +36,7 @@ export function getRefreshTokens(store: Store): Map export function issueAccessToken( store: Store, tokenMap: TokenMap | undefined, - user: GoogleUser, + user: Pick, scope: string, refreshToken: string, ): string { diff --git a/packages/@emulators/google/src/routes/messages.ts b/packages/@emulators/google/src/routes/messages.ts index fe9bed899..f8fa6282d 100644 --- a/packages/@emulators/google/src/routes/messages.ts +++ b/packages/@emulators/google/src/routes/messages.ts @@ -5,6 +5,7 @@ import { createStoredMessage, deleteMessage, dedupeLabelIds, + deliverSentMessage, findMissingLabelIds, formatMessageResource, getAttachmentById, @@ -65,11 +66,12 @@ export function messageRoutes({ app, store }: RouteContext): void { } try { - const message = createStoredMessage(gs, { + const stored = createStoredMessage(gs, { user_email: authEmail, ...messageInput, label_ids: defaultLabelIds, }); + const message = mode === "send" ? deliverSentMessage(gs, stored) : stored; return c.json(formatMessageResource(gs, message, "full")); } catch { diff --git a/packages/@emulators/google/src/routes/oauth.ts b/packages/@emulators/google/src/routes/oauth.ts index f2864d649..2bdf2a950 100644 --- a/packages/@emulators/google/src/routes/oauth.ts +++ b/packages/@emulators/google/src/routes/oauth.ts @@ -16,6 +16,7 @@ import { import { getGoogleStore } from "../store.js"; import type { GoogleUser } from "../entities.js"; import { getRefreshTokens, issueAccessToken, revokeToken } from "../oauth-tokens.js"; +import { JWT_BEARER_GRANT, exchangeServiceAccountAssertion } from "../service-accounts.js"; // RSA key pair generated at module load for signing ID tokens. const keyPairPromise = generateKeyPair("RS256"); @@ -78,6 +79,21 @@ async function createIdToken( return builder.sign(privateKey); } +/** + * Reads client_secret_basic credentials from an Authorization header. Google compares the + * username and password as sent, without the form-decoding RFC 6749 section 2.3.1 describes. + */ +function parseBasicClientCredentials( + header: string | undefined, +): { clientId: string; clientSecret: string } | "malformed" | null { + const match = /^basic\s+(.*)$/i.exec(header ?? ""); + if (!match) return null; + const decoded = Buffer.from(match[1].trim(), "base64").toString("utf8"); + const colon = decoded.indexOf(":"); + if (colon === -1) return "malformed"; + return { clientId: decoded.slice(0, colon), clientSecret: decoded.slice(colon + 1) }; +} + export function oauthRoutes({ app, store, baseUrl, tokenMap }: RouteContext): void { const gs = getGoogleStore(store); @@ -249,17 +265,56 @@ export function oauthRoutes({ app, store, baseUrl, tokenMap }: RouteContext): vo const code = typeof body.code === "string" ? body.code : ""; const redirect_uri = typeof body.redirect_uri === "string" ? body.redirect_uri : ""; const grant_type = typeof body.grant_type === "string" ? body.grant_type : ""; + + // Service accounts authenticate with the signed assertion, not with OAuth client credentials. + if (grant_type === JWT_BEARER_GRANT) { + const assertion = typeof body.assertion === "string" ? body.assertion : ""; + const result = await exchangeServiceAccountAssertion(store, tokenMap, assertion, baseUrl); + if (!result.ok) { + return c.json({ error: result.error, error_description: result.error_description }, result.status); + } + return c.json(result.body); + } const code_verifier = typeof body.code_verifier === "string" ? body.code_verifier : undefined; const bodyClientId = typeof body.client_id === "string" ? body.client_id : ""; const bodyClientSecret = typeof body.client_secret === "string" ? body.client_secret : ""; const clientsConfigured = gs.oauthClients.all().length > 0; + let clientId = bodyClientId; + let clientSecret = bodyClientSecret; if (clientsConfigured) { - const client = gs.oauthClients.findOneBy("client_id", bodyClientId); + const basic = parseBasicClientCredentials(c.req.header("Authorization")); + if (basic === "malformed") { + return c.json({ error: "invalid_request", error_description: "Bad Request" }, 400); + } + if (basic) { + // Body credentials may repeat the header's, but Google refuses ones that differ. + const conflicting = + (bodyClientId !== "" && bodyClientId !== basic.clientId) || + (bodyClientSecret !== "" && (bodyClientId === "" || bodyClientSecret !== basic.clientSecret)); + if (conflicting) { + return c.json( + { + error: "invalid_request", + error_description: "Credentials in post body and basic Authorization header do not match", + }, + 400, + ); + } + if (basic.clientId === "") { + return c.json( + { error: "invalid_request", error_description: "Could not determine client ID from request." }, + 400, + ); + } + ({ clientId, clientSecret } = basic); + } + + const client = gs.oauthClients.findOneBy("client_id", clientId); if (!client) { return c.json({ error: "invalid_client", error_description: "The client_id is incorrect." }, 401); } - if (!constantTimeSecretEqual(bodyClientSecret, client.client_secret)) { + if (!constantTimeSecretEqual(clientSecret, client.client_secret)) { return c.json({ error: "invalid_client", error_description: "The client_secret is incorrect." }, 401); } } @@ -270,7 +325,7 @@ export function oauthRoutes({ app, store, baseUrl, tokenMap }: RouteContext): vo if (!record) { return c.json({ error: "invalid_grant", error_description: "The refresh token is invalid." }, 400); } - if (clientsConfigured && record.clientId !== bodyClientId) { + if (clientsConfigured && record.clientId !== clientId) { return c.json({ error: "invalid_grant", error_description: "The refresh token is invalid." }, 400); } @@ -293,7 +348,7 @@ export function oauthRoutes({ app, store, baseUrl, tokenMap }: RouteContext): vo return c.json( { error: "unsupported_grant_type", - error_description: "Only authorization_code and refresh_token are supported.", + error_description: "Only authorization_code, refresh_token, and the JWT bearer grant are supported.", }, 400, ); diff --git a/packages/@emulators/google/src/service-accounts.ts b/packages/@emulators/google/src/service-accounts.ts new file mode 100644 index 000000000..d9c4af2c9 --- /dev/null +++ b/packages/@emulators/google/src/service-accounts.ts @@ -0,0 +1,217 @@ +import { X509Certificate, createPublicKey, randomBytes, type KeyObject } from "node:crypto"; +import { compactVerify, decodeJwt, decodeProtectedHeader, type JWTPayload, type ProtectedHeaderParameters } from "jose"; +import type { Store, TokenMap } from "@emulators/core"; +import { getGoogleStore } from "./store.js"; +import { issueAccessToken } from "./oauth-tokens.js"; + +export const JWT_BEARER_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer"; + +// The documented audience, plus the older token URLs that existing libraries and Google's own samples still use. +const TOKEN_AUDIENCES = new Set([ + "https://oauth2.googleapis.com/token", + "https://accounts.google.com/o/oauth2/token", + "https://www.googleapis.com/oauth2/v4/token", +]); +const MAX_LIFETIME_SECONDS = 65 * 60; +const CLOCK_SKEW_SECONDS = 5 * 60; + +export interface GoogleSeedServiceAccount { + client_email: string; + client_id: string; + keys: Array<{ + key_id: string; + /** PEM public key or X.509 certificate for the account's private key. */ + public_key: string; + }>; +} + +export interface GoogleSeedDelegation { + /** The service account's numeric client ID, as entered on the Admin console's domain-wide delegation page. */ + client_id: string; + scopes: string[]; +} + +interface StoredServiceAccount { + client_email: string; + client_id: string; + keys: Array<{ key_id: string; public_key: string }>; +} + +const ACCOUNTS_KEY = "google.service_accounts"; +const DELEGATION_KEY = "google.domain_wide_delegation"; + +export function seedServiceAccounts( + store: Store, + accounts: GoogleSeedServiceAccount[] | undefined, + delegation: GoogleSeedDelegation[] | undefined, +): void { + if (accounts) { + const stored = [...(store.getData(ACCOUNTS_KEY) ?? [])]; + for (const account of accounts) { + if (!account.client_email || !account.client_id || !account.keys?.length) { + throw new Error("Google service accounts need client_email, client_id, and at least one key"); + } + for (const key of account.keys) toPublicKey(key.public_key, account.client_email); + const index = stored.findIndex((entry) => entry.client_email === account.client_email); + const entry = { + client_email: account.client_email, + client_id: String(account.client_id), + keys: account.keys.map((key) => ({ key_id: key.key_id, public_key: key.public_key })), + }; + if (index === -1) stored.push(entry); + else stored[index] = entry; + } + store.setData(ACCOUNTS_KEY, stored); + } + + if (delegation) { + const stored = new Map( + (store.getData(DELEGATION_KEY) ?? []).map((entry) => [entry.client_id, entry]), + ); + for (const entry of delegation) { + stored.set(String(entry.client_id), { client_id: String(entry.client_id), scopes: [...(entry.scopes ?? [])] }); + } + store.setData(DELEGATION_KEY, [...stored.values()]); + } +} + +/** The seeded service account with this email, which strict mode accepts as a token's subject. */ +export function findServiceAccount(store: Store, email: string): { email: string; id: number } | undefined { + const account = (store.getData(ACCOUNTS_KEY) ?? []).find( + (entry) => entry.client_email === email, + ); + return account ? { email: account.client_email, id: 0 } : undefined; +} + +function toPublicKey(pem: string, account: string): KeyObject { + try { + return pem.includes("BEGIN CERTIFICATE") ? new X509Certificate(pem).publicKey : createPublicKey(pem); + } catch { + throw new Error(`Google service account ${account} has a key that is not a PEM public key or certificate`); + } +} + +type TokenError = { status: 400 | 401 | 403; error: string; error_description: string }; +type TokenResult = { ok: true; body: Record } | ({ ok: false } & TokenError); + +const fail = (status: TokenError["status"], error: string, error_description: string): TokenResult => ({ + ok: false, + status, + error, + error_description, +}); + +/** + * Exchanges a service account's signed JWT for an access token, following + * https://developers.google.com/identity/protocols/oauth2/service-account. With a `sub` claim, the + * token acts as that user, which needs domain-wide delegation for every requested scope. + */ +export async function exchangeServiceAccountAssertion( + store: Store, + tokenMap: TokenMap | undefined, + assertion: string, + baseUrl: string, + now = Math.floor(Date.now() / 1000), +): Promise { + let header: ProtectedHeaderParameters; + let claims: JWTPayload; + try { + header = decodeProtectedHeader(assertion); + claims = decodeJwt(assertion); + } catch { + return fail(400, "invalid_request", "Bad Request"); + } + + const scopes = typeof claims.scope === "string" ? claims.scope.split(" ").filter(Boolean) : []; + if (scopes.length === 0) { + return fail(400, "invalid_scope", "Invalid OAuth scope or ID token audience provided."); + } + + const gs = getGoogleStore(store); + const subject = typeof claims.sub === "string" && claims.sub ? claims.sub : undefined; + const user = subject + ? gs.users.all().find((candidate) => candidate.email.toLowerCase() === subject.toLowerCase()) + : undefined; + if (subject && !user) return fail(400, "invalid_grant", "Not a valid email or user ID."); + + const account = (store.getData(ACCOUNTS_KEY) ?? []).find( + (entry) => entry.client_email === claims.iss, + ); + if (!account) return fail(400, "invalid_grant", "Invalid grant: account not found"); + + if (!(await verifySignature(assertion, header, account))) { + return fail(400, "invalid_grant", "Invalid JWT Signature."); + } + + const audiences = Array.isArray(claims.aud) ? claims.aud : [claims.aud]; + // Clients whose token_uri points at the emulator sign its own token URL as the audience. + const emulatorAudience = `${baseUrl.replace(/\/+$/, "")}/oauth2/token`; + if (!audiences.some((aud) => typeof aud === "string" && (TOKEN_AUDIENCES.has(aud) || aud === emulatorAudience))) { + return fail(400, "invalid_grant", "Invalid JWT: Invalid audience."); + } + + const { iat, exp } = claims; + if ( + typeof iat !== "number" || + typeof exp !== "number" || + exp < iat || + exp - iat > MAX_LIFETIME_SECONDS || + iat > now + CLOCK_SKEW_SECONDS || + exp < now - CLOCK_SKEW_SECONDS + ) { + return fail( + 400, + "invalid_grant", + "Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your iat and exp values in the JWT claim.", + ); + } + + if (user) { + const delegation = (store.getData(DELEGATION_KEY) ?? []).find( + (entry) => entry.client_id === account.client_id, + ); + if (!delegation) return fail(401, "unauthorized_client", "Unauthorized client or scope in request."); + const granted = scopes.filter((scope) => delegation.scopes.includes(scope)); + if (granted.length === 0) { + return fail( + 401, + "unauthorized_client", + "Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested.", + ); + } + if (granted.length < scopes.length) return fail(403, "access_denied", "Requested client not authorized."); + } + + const scope = scopes.join(" "); + // Service account tokens have no refresh token, so each one gets its own revocation key. + const revocationKey = "google_sa_" + randomBytes(12).toString("base64url"); + const accessToken = issueAccessToken( + store, + tokenMap, + user ?? { email: account.client_email, id: 0 }, + scope, + revocationKey, + ); + return { ok: true, body: { access_token: accessToken, expires_in: 3600, scope, token_type: "Bearer" } }; +} + +async function verifySignature( + assertion: string, + header: ProtectedHeaderParameters, + account: StoredServiceAccount, +): Promise { + if (header.alg !== "RS256") return false; + // A key ID that names none of the account's keys falls back to trying every key, as Google documents. + const named = account.keys.filter((key) => key.key_id === header.kid); + const candidates = + named.length > 0 ? [...named, ...account.keys.filter((key) => !named.includes(key))] : account.keys; + for (const key of candidates) { + try { + await compactVerify(assertion, toPublicKey(key.public_key, account.client_email), { algorithms: ["RS256"] }); + return true; + } catch { + // Try the next key. + } + } + return false; +} diff --git a/packages/emulate/src/program.ts b/packages/emulate/src/program.ts index abd1323f1..2b150c070 100644 --- a/packages/emulate/src/program.ts +++ b/packages/emulate/src/program.ts @@ -98,6 +98,8 @@ Google OIDC: Discovery advertises RS256 ID tokens, and GET /oauth2/v3/certs returns the RSA public key used to verify them. Set google.strict_scopes: true in seed config to validate issued access tokens, expiry, revocation, and method scopes. Strict mode returns Google-style 401/403 errors and limits userinfo claims; bearer-token defaults remain permissive. + POST /oauth2/token accepts service account JWT assertions for google.service_accounts; a sub claim needs + google.domain_wide_delegation for every requested scope. Resend API coverage: POST /emails and POST /emails/batch support 24-hour Idempotency-Key replay without duplicate emails or webhooks. diff --git a/packages/emulate/src/registry.ts b/packages/emulate/src/registry.ts index 4891200ca..8dc172222 100644 --- a/packages/emulate/src/registry.ts +++ b/packages/emulate/src/registry.ts @@ -142,7 +142,7 @@ export const SERVICE_REGISTRY: Record = { google: { label: "Google OAuth 2.0 / OpenID Connect + Gmail, Calendar, and Drive emulator", endpoints: - "OAuth authorize, token exchange, userinfo, RS256 OIDC discovery and JWKS, token revocation, Gmail messages/drafts/threads/labels/history/settings, Calendar discovery/lists/events/freebusy, Drive files/uploads", + "OAuth authorize, token exchange, service account tokens with domain-wide delegation, userinfo, RS256 OIDC discovery and JWKS, token revocation, Gmail messages/drafts/threads/labels/history/settings, Calendar discovery/lists/events/freebusy, Drive files/uploads", async load() { const mod = await import("@emulators/google"); return { plugin: mod.googlePlugin, seedFromConfig: mod.seedFromConfig }; diff --git a/skills/google/SKILL.md b/skills/google/SKILL.md index 2f61e813a..435c7c2d5 100644 --- a/skills/google/SKILL.md +++ b/skills/google/SKILL.md @@ -232,6 +232,18 @@ redirect_uri=http://localhost:3000/api/auth/callback/google&\ grant_type=authorization_code" ``` +The client can also send its credentials in an HTTP Basic `Authorization` header (`client_secret_basic`): + +```bash +curl -X POST http://localhost:4002/oauth2/token \ + -u "my-client-id.apps.googleusercontent.com:GOCSPX-secret" \ + -d "code=&\ +redirect_uri=http://localhost:3000/api/auth/callback/google&\ +grant_type=authorization_code" +``` + +Body credentials sent with the header must repeat it: a different `client_id` or `client_secret`, or a `client_secret` without `client_id`, returns `400 invalid_request`. The Basic username and password are compared as sent, without form-decoding, as Google does. Client credentials are only checked when OAuth clients are configured. + Also accepts `application/json` body. Returns: ```json @@ -273,6 +285,38 @@ curl -X POST http://localhost:4002/oauth2/revoke \ -d "token=google_..." ``` +### Service Accounts + +`POST /oauth2/token` accepts the JWT bearer grant (`grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`) for service accounts seeded under `google.service_accounts`. Each key takes the `key_id` from the account's key file and its PEM public key or X.509 certificate, so the private key stays with the code under test. + +```yaml +google: + users: + - email: alice@example.com + service_accounts: + - client_email: archiver@my-project.iam.gserviceaccount.com + client_id: "104523180291234567890" + keys: + - key_id: 5f0c2b7e9a + public_key: | + -----BEGIN PUBLIC KEY----- + ... + -----END PUBLIC KEY----- + domain_wide_delegation: + - client_id: "104523180291234567890" + scopes: + - https://www.googleapis.com/auth/gmail.readonly +``` + +The assertion must be RS256-signed by one of the account's keys, with `iss` set to the account's `client_email`, a space-delimited `scope`, `aud` set to `https://oauth2.googleapis.com/token` or the emulator's own `/oauth2/token` URL, and an `exp` at most 65 minutes after `iat`. A `kid` that names none of the account's keys falls back to trying every key. The response has `access_token`, `expires_in: 3600`, `scope`, and `token_type: Bearer`, and no refresh token. Without `sub`, the token acts as the service account, including under `google.strict_scopes`. With `sub`, it acts as that user, and every requested scope must be granted to the account's `client_id` under `google.domain_wide_delegation`. Under `google.strict_scopes`, Gmail, Calendar, and Drive check the token's scopes as they do for other tokens. + +Errors follow Google's JWT error table: `invalid_scope` for an empty `scope`, `invalid_grant` for an unknown `sub` user, an unknown account, a bad signature, a wrong audience, or an expired or too-long-lived assertion, `401 unauthorized_client` when the account has no delegation or none of the requested scopes are delegated, and `403 access_denied` when only some of them are. The other errors return `400`. User suspension, key expiry, and `target_audience` ID tokens are not modeled. + +```bash +curl -X POST http://localhost:4002/oauth2/token \ + -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=" +``` + ## Gmail API All Gmail endpoints are under `/gmail/v1/users/:userId/...` where `:userId` is `me` or the authenticated user's email. @@ -341,6 +385,8 @@ curl http://localhost:4002/gmail/v1/users/me/messages/msg_id/attachments/att_id Upload variants also available at `/upload/gmail/v1/users/:userId/messages`, `.../messages/send`, `.../messages/import`. +`messages.send` and `drafts.send` deliver the message to each `To`, `Cc`, and `Bcc` recipient who is a user of the emulator. Before delivery, `From` must be a single mailbox whose address is one of the sender's send-as addresses (`GET .../settings/sendAs`). Otherwise it is replaced with their default send-as address. Either way, the message fields and the raw MIME `From` are rebuilt from the checked name and address. The recipient gets a copy labeled `INBOX` and `UNREAD`, without the `Bcc` header, threaded with the messages it replies to in their mailbox, and with their filters applied. Recipients who aren't emulator users are skipped. A message sent to yourself stays one message, labeled `SENT`, `INBOX`, and `UNREAD`, unless your own filters remove those labels. `messages.insert` and `messages.import` don't deliver. + ### Drafts ```bash