@lanes-sh/link 0.1.0

package/src/providers/google/gmail/send.ts

@@ -0,0 +1,365 @@
+import { z } from 'zod';
+import type { ProviderContext, ToolCapability, ToolResult } from '#connectivity';
+import {
+  attachmentRefSchema,
+  composeMime,
+  receiptFor,
+  resolveAttachments,
+  type ResolvedAttachment,
+} from '#connectivity/mail';
+import {
+  GMAIL_API,
+  GMAIL_JSON_LIMIT_BYTES,
+  GMAIL_MAX_MESSAGE_BYTES,
+  GMAIL_UPLOAD,
+} from './api.ts';
+import { gmailAttachments } from './attachment.ts';
+
+/**
+ * Sending mail, composed here rather than by the caller.
+ *
+ * The one capability on this provider that is code instead of data, and the
+ * reason is narrow: Gmail's API takes a whole assembled RFC 2822 message as one
+ * base64url field. Nothing in an OpenAPI document describes composing one, so the
+ * generated tools hand that job to the caller — which for a plain message is
+ * merely absurd, and for a message with an attachment is impossible. A 239 KB PDF
+ * is about 320,000 characters of base64, past what a model can write in one
+ * message. That is a real failure someone hit, not a hypothetical.
+ *
+ * Note there was no send tool here at all before this. The omission was
+ * deliberate — "the token can send, the tool surface cannot" — and reversing it
+ * is the point of the change rather than an accident of it. `gmail.compose`
+ * already permits it, `draft_only` keeps the review step available, and
+ * `lanes link policy deny gmail.send_message` still takes it away.
+ *
+ * `draft_id` extends the same argument to revising one. The generated
+ * `drafts.update` had the identical defect its sibling `drafts.create` was
+ * removed for — a `Draft` body whose `message.raw` the caller assembles — so
+ * correcting a draft that carried a file meant deleting it and composing the
+ * whole thing again, re-fetching every attachment on the way. Here the message
+ * is recomposed as it always was and the only difference is the address it goes
+ * to: a `PUT` at the draft rather than a `POST` at the collection.
+ *
+ * Sending after a revision is two requests rather than one. Gmail's
+ * `drafts.send` does accept a whole `Draft`, which would fold the update into
+ * the send, but the merge semantics are not something this code can verify from
+ * here — and the failure mode if they are not what one assumed is that the
+ * *previous* draft goes out, silently, to real recipients. Updating and then
+ * sending by id costs a round trip on a path already measured in seconds, and
+ * both halves are documented single-purpose calls.
+ */
+
+const schema = z.object({
+  to: z.array(z.string()).min(1).describe('Recipients.'),
+  cc: z.array(z.string()).optional(),
+  bcc: z.array(z.string()).optional(),
+  subject: z.string(),
+  text: z.string().optional().describe('Plain-text body.'),
+  html: z.string().optional().describe('HTML body. Send text as well where you can.'),
+  in_reply_to: z
+    .string()
+    .optional()
+    .describe('Message-ID being replied to, which threads the reply.'),
+  from_name: z
+    .string()
+    .optional()
+    .describe(
+      'Name to show beside the address. Rarely needed here — omitted, Gmail fills in the account\'s own name — so pass it only to send under a different one.',
+    ),
+  attachments: z
+    .array(attachmentRefSchema)
+    .optional()
+    .describe(
+      'Files to attach, each named by reference. This endpoint reads the bytes itself — never encode a file into this call.',
+    ),
+  // The warning in the description is there because the failure happened. A
+  // draft carrying a 204 KB PDF took 19 seconds — the bytes were pulled back
+  // out of the mailbox and re-uploaded — and the client, having no result it
+  // trusted, listed the drafts and then sent the identical call twice more.
+  // Three drafts, all of them ours to explain. Nothing here retries, so the
+  // repair is telling the caller what a slow call means and giving it
+  // `drafts.list` and `drafts.delete` to act on, rather than inventing an
+  // idempotency key this endpoint has nowhere to keep.
+  draft_only: z
+    .boolean()
+    .optional()
+    .describe(
+      'Save as a draft instead of sending, so it can be reviewed first. This call is not idempotent and a message with an attachment can take tens of seconds, because the bytes are fetched and uploaded here: if it appears to time out, the draft may already exist. List drafts to check before calling again, and delete the surplus one rather than leaving both.',
+    ),
+  draft_id: z
+    .string()
+    .optional()
+    .describe(
+      'Revise this existing draft instead of writing a new one — pass the id a previous call returned. Every other argument describes the message as it should now read, because the draft is replaced rather than merged into: name the attachments again to keep them. With draft_only the revision stays a draft; without it, the revised draft is sent.',
+    ),
+});
+
+/**
+ * Built rather than declared, so `fetch` can be substituted in a test.
+ *
+ * The same seam every transport here offers. Without it a test has to reach for
+ * the global, and a test that patches `globalThis` leaks into whatever runs
+ * beside it.
+ */
+export function gmailSend(
+  options: { readonly fetch?: typeof globalThis.fetch } = {},
+): ToolCapability<typeof schema> {
+  const doFetch = options.fetch ?? globalThis.fetch;
+
+  return {
+    kind: 'tool',
+    name: 'send_message',
+    description:
+      'Send a message, with attachments, or save it as a draft. Attachments are named by reference — a path on this machine, an HTTPS URL, a staged handle, or another message in this mailbox — and this endpoint fetches the bytes itself, so never encode a file into the call.',
+    inputSchema: schema,
+
+    async handler(input, context): Promise<ToolResult> {
+      const authorize = context.authorize;
+      if (!authorize) {
+        // Only reachable if this capability is ever registered on a provider with
+        // no credential, which the manifest makes impossible. Stated rather than
+        // asserted non-null, so the failure names its cause.
+        return fail('This connection has no credential, so it cannot send.');
+      }
+
+      let attachments: ResolvedAttachment[];
+      try {
+        attachments = await resolveAttachments(input.attachments, {
+          // Three quarters of the ceiling: attachments travel base64, so this is
+          // the raw weight that fits once encoded. The composed message is measured
+          // exactly below.
+          maxTotalBytes: Math.floor((GMAIL_MAX_MESSAGE_BYTES * 3) / 4),
+          signal: context.signal,
+          mailbox: gmailAttachments({ authorize, fetch: doFetch, signal: context.signal }),
+          storage: context.storage,
+        });
+      } catch (failure) {
+        return fail((failure as Error).message);
+      }
+
+      // Normally no `From` at all: Gmail fills it from the credential, name
+      // included, which is better than anything guessable here — and inventing an
+      // address risks writing one this account may not send as. A name is written
+      // only when someone asked for one, and then the address has to come with it,
+      // since a display name alone is not a header.
+      const configured = context.connection.config['from_name'];
+      const fromName =
+        input.from_name ??
+        (typeof configured === 'string' && configured.trim() !== '' ? configured : undefined);
+      const address = context.connection.displayName;
+
+      const composed = await composeMime({
+        ...(fromName && address.includes('@') ? { from: address, fromName } : {}),
+        message: {
+          to: input.to,
+          cc: input.cc,
+          bcc: input.bcc,
+          subject: input.subject,
+          text: input.text,
+          html: input.html,
+          inReplyTo: input.in_reply_to,
+          ...(attachments.length > 0 ? { attachments } : {}),
+        },
+      });
+
+      if (composed.raw.byteLength > GMAIL_MAX_MESSAGE_BYTES) {
+        return fail(
+          `The composed message is ${composed.raw.byteLength} bytes and Gmail accepts ${GMAIL_MAX_MESSAGE_BYTES}. Attachments are base64 in transit, so they weigh about a third more than on disk.`,
+        );
+      }
+
+      // Recorded before submitting, so a file read off disk is in the log even if
+      // the send then fails. `redact` cannot express this — it keeps an argument
+      // verbatim, and `attachments` may itself hold a base64 file.
+      if (attachments.length > 0) {
+        context.audit.annotate({
+          attachments: attachments.map((attachment) => ({
+            filename: attachment.filename,
+            bytes: attachment.bytes.byteLength,
+            content_type: attachment.contentType,
+            sha256: attachment.sha256,
+            origin: attachment.origin,
+          })),
+        });
+      }
+
+      const drafting = input.draft_only === true;
+
+      try {
+        let sent = await submit({
+          raw: composed.raw,
+          draftOnly: drafting,
+          draftId: input.draft_id,
+          authorize,
+          fetch: doFetch,
+          context,
+        });
+
+        // A revision that is not staying a draft is sent by id, now that the
+        // draft holds the new message. Its own failure is reported separately
+        // from the update's, because the two leave the mailbox in different
+        // states and only one of them is worth retrying as composed.
+        if (input.draft_id !== undefined && !drafting) {
+          try {
+            sent = await sendDraft({
+              draftId: input.draft_id,
+              authorize,
+              fetch: doFetch,
+              context,
+            });
+          } catch (failure) {
+            return fail(
+              `The draft was revised but not sent: ${(failure as Error).message} The new message is saved as draft ${input.draft_id}, so send that rather than composing it again.`,
+            );
+          }
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(
+                {
+                  ...(drafting
+                    ? { drafted: true, draft_id: sent['id'] ?? input.draft_id ?? null }
+                    : { sent: true }),
+                  message_id: messageIdOf(sent) ?? composed.messageId,
+                  recipients: input.to.length + (input.cc?.length ?? 0) + (input.bcc?.length ?? 0),
+                  // Names, sizes and digests, never content — see `receiptFor`.
+                  ...(attachments.length > 0
+                    ? { attachments: attachments.map(receiptFor) }
+                    : {}),
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (failure) {
+        return fail((failure as Error).message);
+      }
+    },
+  };
+}
+
+/** The wired capability, as the provider declares it. */
+export const gmailSendMessage = gmailSend();
+
+/**
+ * Hand the assembled message to Gmail.
+ *
+ * Two routes, chosen by size. A small message goes as base64url in a JSON field,
+ * which is the ordinary endpoint and the overwhelmingly common case. A large one
+ * goes to the upload host as `message/rfc822` with the raw MIME as the body —
+ * `uploadType=media`, no multipart assembly, no resumable session — which is what
+ * lifts the ceiling from "what fits in a JSON string" to Gmail's own 35 MiB.
+ */
+async function submit(input: {
+  readonly raw: Uint8Array;
+  readonly draftOnly: boolean;
+  readonly draftId: string | undefined;
+  readonly authorize: (request: Request) => Promise<Request>;
+  readonly fetch: typeof globalThis.fetch;
+  readonly context: ProviderContext;
+}): Promise<Record<string, unknown>> {
+  const { raw, draftOnly, draftId, authorize, context } = input;
+  const large = raw.byteLength > GMAIL_JSON_LIMIT_BYTES;
+
+  // Revising is a `PUT` at the draft's own address; the other two are a `POST`
+  // at a collection. The upload host takes the same path either way, so size
+  // still chooses the host and nothing else.
+  const revising = draftId !== undefined;
+  const path = revising
+    ? `/drafts/${encodeURIComponent(draftId)}`
+    : draftOnly
+      ? '/drafts'
+      : '/messages/send';
+  const url = large ? `${GMAIL_UPLOAD}${path}?uploadType=media` : `${GMAIL_API}${path}`;
+
+  const encoded = large ? undefined : Buffer.from(raw).toString('base64url');
+  // A draft nests the message, whether it is being created or replaced; only a
+  // straight send carries `raw` at the top level.
+  const body: Uint8Array | string = large
+    ? raw
+    : JSON.stringify(draftOnly || revising ? { message: { raw: encoded } } : { raw: encoded });
+
+  const request = await authorize(
+    new Request(url, {
+      method: revising ? 'PUT' : 'POST',
+      headers: {
+        'content-type': large ? 'message/rfc822' : 'application/json',
+        accept: 'application/json',
+      },
+      body,
+      ...(context.signal ? { signal: context.signal } : {}),
+    }),
+  );
+
+  const response = await input.fetch(request);
+  const text = await response.text();
+
+  if (!response.ok) {
+    throw new Error(`Gmail refused the message with ${response.status}: ${text}`);
+  }
+
+  try {
+    return JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Send a draft that already exists, by id.
+ *
+ * Always small — the body is one identifier — so there is no upload-host branch
+ * here even when the draft it names carries 30 MiB. The bytes were already
+ * handed over by the `PUT` that preceded this.
+ */
+async function sendDraft(input: {
+  readonly draftId: string;
+  readonly authorize: (request: Request) => Promise<Request>;
+  readonly fetch: typeof globalThis.fetch;
+  readonly context: ProviderContext;
+}): Promise<Record<string, unknown>> {
+  const request = await input.authorize(
+    new Request(`${GMAIL_API}/drafts/send`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify({ id: input.draftId }),
+      ...(input.context.signal ? { signal: input.context.signal } : {}),
+    }),
+  );
+
+  const response = await input.fetch(request);
+  const text = await response.text();
+
+  if (!response.ok) {
+    throw new Error(`Gmail refused to send the draft with ${response.status}: ${text}`);
+  }
+
+  try {
+    return JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+/** Gmail answers with its own id; a draft nests the message inside. */
+function messageIdOf(body: Record<string, unknown>): string | null {
+  const id = body['id'];
+  if (typeof id === 'string' && !('message' in body)) return id;
+
+  const message = body['message'];
+  if (message !== null && typeof message === 'object') {
+    const nested = (message as { id?: unknown }).id;
+    if (typeof nested === 'string') return nested;
+  }
+
+  return typeof id === 'string' ? id : null;
+}
+
+function fail(message: string): ToolResult {
+  return { content: [{ type: 'text', text: message }], isError: true };
+}

package/src/providers/google/gmail-mcp/index.ts

@@ -0,0 +1,35 @@
+import { defineProvider } from '#connectivity';
+import { GMAIL_IDENTITY, GOOGLE_APP } from '../shared/oauth.ts';
+import { googleSetup } from '../shared/setup.ts';
+
+/**
+ * Gmail via Google's MCP server. Workspace Developer Preview members only.
+ *
+ * Deliberately not `GMAIL_SCOPES`. The server *advertises* five, including
+ * `mail.google.com` — read, send, and permanently delete. Requesting the full
+ * advertised set was tried, on the theory that the servers reject a subset, and
+ * it made no difference: with all five granted, `tools/list` succeeds and every
+ * `tools/call` still answers "The caller does not have permission". The gate is
+ * enrolment in Google's Workspace Developer Preview, not scope.
+ *
+ * That is the opposite of the REST provider's situation, where scope is exactly
+ * the gate — hence two lists. Widening this one buys nothing that has been
+ * demonstrated, so it stays at what Google documents. If calls still fail once
+ * preview access is granted, widening is the next thing to try — `connect` warns
+ * about the gap either way.
+ */
+const GMAIL_MCP_SCOPES = [
+  'https://www.googleapis.com/auth/gmail.readonly',
+  'https://www.googleapis.com/auth/gmail.compose',
+];
+
+export const gmailMcp = defineProvider({
+  id: 'gmail_mcp',
+  name: 'Gmail (Google MCP)',
+  description:
+    'Read and compose mail via Google\'s official Gmail MCP server. Requires Workspace Developer Preview enrolment — use "gmail" otherwise.',
+  connector: { kind: 'mcp', endpoint: 'https://gmailmcp.googleapis.com/mcp/v1' },
+  auth: { kind: 'oauth', registration: 'manual', app: GOOGLE_APP, scopes: GMAIL_MCP_SCOPES },
+  identity: GMAIL_IDENTITY,
+  setup: googleSetup('Gmail', GMAIL_MCP_SCOPES, { preview: true }),
+});

package/src/providers/google/index.ts

@@ -0,0 +1,10 @@
+/** Google's nine providers. Each folder holds all of its own vendor knowledge. */
+export { calendar } from './calendar/index.ts';
+export { contacts } from './contacts/index.ts';
+export { docs } from './docs/index.ts';
+export { drive, DRIVE_SCOPES } from './drive/index.ts';
+export { driveMcp } from './drive-mcp/index.ts';
+export { gmail, GMAIL_SCOPES } from './gmail/index.ts';
+export { gmailMcp } from './gmail-mcp/index.ts';
+export { sheets } from './sheets/index.ts';
+export { tasks } from './tasks/index.ts';

package/src/providers/google/shared/oauth.ts

@@ -0,0 +1,122 @@
+import type { AuthBroker } from '#connectivity';
+import { brokerOriginOverride } from '#connectivity/auth/index.ts';
+
+/**
+ * Google's OAuth endpoints, shared by every Google provider.
+ *
+ * A REST API announces nothing about where its authorization server lives, so
+ * an `http` connector has to be told. `access_type=offline` and
+ * `prompt=consent` are what make Google return a refresh token at all — without
+ * them the connection works for an hour and then dies.
+ */
+export const GOOGLE_APP = 'google';
+
+/**
+ * The Google OAuth client Lanes operates, and where its secret stays.
+ *
+ * Its own Cloud project, separate from the one that signs people into Lanes:
+ * this client asks for Gmail and Drive and carries a verification review that
+ * can be rejected, and a rejection must not be able to take sign-in with it.
+ *
+ * The secret is not confidential in Google's sense — an installed app cannot
+ * hold one — and is held back anyway. Shipping it would hand anyone the shared
+ * quota and standing of a single client that every Lanes Link user depends on,
+ * and there is no way to withdraw one copy of a secret.
+ *
+ * What this buys the operator is the whole of `setup/google.md`: no project, no
+ * console, no scope list to transcribe, and no seven-day refresh-token expiry,
+ * because that expiry is a property of a project left in "Testing" and this one
+ * is not. What it costs is recorded in ADR-028 and in the guarantee table in
+ * `docs/detailed/security.md` — chiefly that the exchange stops being local.
+ */
+const BROKER_ORIGIN = 'https://api.lanes.sh';
+const BROKER_PATH = '/v1/auth/link/google';
+
+/**
+ * The same client, reached at a different origin.
+ *
+ * Two callers need it: the CLI performing the first exchange and the dispatcher
+ * refreshing while it serves. Both read `manifest.auth.broker.url`, so building
+ * it once here is what keeps them from disagreeing about where the broker is —
+ * and what makes `LANES_LINK_BROKER_ORIGIN` reach both at once. The path stays
+ * fixed; only the host in front of it moves. See `../../../connectivity/auth/
+ * oauth-authcode/broker.ts` for what an override is allowed to be.
+ */
+export function googleBroker(env?: Record<string, string | undefined>): AuthBroker {
+  return {
+    url: `${brokerOriginOverride(env) ?? BROKER_ORIGIN}${BROKER_PATH}`,
+    operator: 'Lanes',
+    docs_url: 'https://lanes.sh/link#google',
+  };
+}
+
+export const GOOGLE_BROKER: AuthBroker = googleBroker();
+
+export const GOOGLE_OAUTH = {
+  authorize_url: 'https://accounts.google.com/o/oauth2/v2/auth',
+  token_url: 'https://oauth2.googleapis.com/token',
+  //
+  // `select_account` matters as much as the rest: with it omitted Google reuses
+  // whichever account the browser is already signed into and never offers a
+  // choice, so connecting a second mailbox silently re-authorises the first.
+  authorize_params: { access_type: 'offline', prompt: 'select_account consent' },
+  // Every REST provider here spreads this block, so one line turns brokering on
+  // for all seven. `gmail_mcp` and `drive_mcp` write their auth longhand and do
+  // not spread it, which is what keeps them bring-your-own — the SDK owns their
+  // exchange and `defineProvider` refuses a broker on an mcp connector.
+  broker: GOOGLE_BROKER,
+} as const;
+
+/**
+ * Where a Google provider reads its account label from.
+ *
+ * Drive's endpoint, deliberately, for Sheets and Docs as well: neither has a
+ * "who am I", and `drive.readonly` is requested anyway, so labelling the
+ * connection costs no extra consent.
+ */
+export const DRIVE_IDENTITY = {
+  kind: 'http',
+  url: 'https://www.googleapis.com/drive/v3/about?fields=user',
+  field: 'user.emailAddress',
+} as const;
+
+export const GMAIL_IDENTITY = {
+  kind: 'http',
+  url: 'https://gmail.googleapis.com/gmail/v1/users/me/profile',
+  field: 'emailAddress',
+} as const;
+
+/**
+ * Calendar answers this itself, rather than borrowing Drive's endpoint.
+ *
+ * The entry for someone's own calendar is keyed by their address, so its `id`
+ * *is* the label — and it reads under `calendar.readonly`, which this provider
+ * requests anyway. Following Sheets and Docs to `DRIVE_IDENTITY` would mean
+ * asking for `drive.readonly` purely to print a name.
+ */
+export const CALENDAR_IDENTITY = {
+  kind: 'http',
+  url: 'https://www.googleapis.com/calendar/v3/users/me/calendarList/primary',
+  field: 'id',
+} as const;
+
+/**
+ * Contacts asks People who the token belongs to — using the very operation that
+ * cannot be a *tool*.
+ *
+ * `people.people.get` is unreachable through the generated path, because
+ * `{resourceName}` has its slash percent-encoded and `people/me` stops being a
+ * path (see the note in `../specs/vendor.ts`). A literal URL has no placeholder
+ * to encode, so the same call works here. `pluck` steps through the first array
+ * element, which is what resolves `emailAddresses.value`.
+ */
+export const PEOPLE_IDENTITY = {
+  kind: 'http',
+  url: 'https://people.googleapis.com/v1/people/me?personFields=emailAddresses',
+  field: 'emailAddresses.value',
+} as const;
+
+/** A vendored spec, addressed from this folder rather than by counting `..`. */
+export function specPath(name: string): string {
+  return new URL(`../specs/${name}`, import.meta.url).pathname;
+}

package/src/providers/google/shared/scopes.ts

@@ -0,0 +1,99 @@
+import type { ScopeMeaning } from '../../scopes.ts';
+
+/**
+ * What the Google scopes we ship actually permit, in plain words.
+ *
+ * Vendor knowledge, so it lives with the vendor. It used to sit in the CLI,
+ * which is where it is *displayed* — but a table of Google scope semantics in
+ * `src/cli/` is exactly the leak this layout exists to close: `lanes link
+ * connect` should be able to explain any provider's grant without the CLI
+ * having learned that provider's vocabulary.
+ *
+ * Confined to display. Nothing routes on it, and a scope missing from this table
+ * is printed unannotated rather than mis-described — silence is the safe failure
+ * here.
+ */
+export const GOOGLE_SCOPE_MEANINGS: Record<string, ScopeMeaning> = {
+  // Asked for only when authorising against the client Lanes operates, which
+  // needs to tell one caller's refresh from another's. Neither reaches any
+  // Google service, and describing them matters precisely because they are the
+  // two the operator did not ask for.
+  openid: { meaning: 'a signed statement of which Google account this is — no access to anything' },
+  email: {
+    meaning: 'your address, so the hosted client can tell whose connection this is. Not the mailbox',
+  },
+  'https://mail.google.com/': {
+    meaning: 'full mailbox — read, send, and permanently delete any message',
+    broad: true,
+  },
+  'https://www.googleapis.com/auth/gmail.modify': {
+    meaning: 'read, send, and modify any message; no permanent delete',
+    broad: true,
+  },
+  'https://www.googleapis.com/auth/gmail.readonly': { meaning: 'read mail and settings' },
+  'https://www.googleapis.com/auth/gmail.compose': { meaning: 'create and send drafts' },
+  'https://www.googleapis.com/auth/gmail.settings.basic': {
+    // Broad for what it *outlives*, not for how much it touches. A filter keeps
+    // acting on mail that has not arrived yet, so this is the only grant here
+    // that survives the session, the token, and the connection being disabled.
+    meaning: 'create and delete filters, and change your send-as identities — a filter is a standing rule that keeps acting after the session ends',
+    broad: true,
+  },
+  'https://www.googleapis.com/auth/gmail.metadata': {
+    meaning: 'headers and labels only, no message bodies',
+  },
+  'https://www.googleapis.com/auth/drive': {
+    meaning: 'every file in the account — read, write, and delete',
+    broad: true,
+  },
+  'https://www.googleapis.com/auth/drive.readonly': { meaning: 'read every file in the account' },
+  'https://www.googleapis.com/auth/drive.file': {
+    meaning: 'only files this app creates or you pick',
+  },
+  // Broad, and narrower than `auth/drive` — one file type rather than the whole
+  // account. Still every document of that type, including ones this app has
+  // never seen, which is the line `drive.file` does not cross.
+  'https://www.googleapis.com/auth/spreadsheets': {
+    meaning: 'every spreadsheet in the account — read, edit, create, and delete',
+    broad: true,
+  },
+  'https://www.googleapis.com/auth/documents': {
+    meaning: 'every document in the account — read, edit, create, and delete',
+    broad: true,
+  },
+  // Calendar's `auth/drive`: it does not merely edit what is on a calendar, it
+  // creates and deletes calendars and changes who they are shared with. Listed
+  // so the table can say what is refused, never requested.
+  'https://www.googleapis.com/auth/calendar': {
+    meaning: 'every calendar you can access — read, edit, share, and delete',
+    broad: true,
+  },
+  'https://www.googleapis.com/auth/calendar.readonly': {
+    meaning: 'read every calendar you can access',
+  },
+  // Broad on the same reading as `spreadsheets` — every event on every
+  // calendar, including ones this app has never seen. Narrower than
+  // `auth/calendar`, which also reaches the calendars themselves.
+  'https://www.googleapis.com/auth/calendar.events': {
+    meaning: 'every event on every calendar — read, create, change, and delete',
+    broad: true,
+  },
+  // Broad because Google publishes nothing narrower that can write. `tasks` and
+  // `tasks.readonly` are the entire vocabulary, so adding one task means
+  // holding write and delete over every list in the account.
+  'https://www.googleapis.com/auth/tasks': {
+    meaning: 'every task list — read, create, edit, organise, and delete',
+    broad: true,
+  },
+  'https://www.googleapis.com/auth/tasks.readonly': { meaning: 'read your task lists and tasks' },
+  // Refused, and listed for the same reason as `auth/calendar`: a contact card
+  // deleted through the API is gone.
+  'https://www.googleapis.com/auth/contacts': {
+    meaning: 'read, edit, and permanently delete your contacts',
+    broad: true,
+  },
+  'https://www.googleapis.com/auth/contacts.readonly': { meaning: 'read your saved contacts' },
+  'https://www.googleapis.com/auth/contacts.other.readonly': {
+    meaning: 'read the addresses Gmail saved automatically in "Other contacts"',
+  },
+};