@lanes-sh/link 0.6.11 → 0.7.0

package/src/providers/microsoft/mail/index.ts

@@ -0,0 +1,76 @@
+import { defineProvider } from '#connectivity';
+import {
+  CALENDAR_SCOPES,
+  CONTACTS_SCOPES,
+  FILES_SCOPES,
+  GRAPH_BASE_URL,
+  MAIL_SCOPES,
+  MICROSOFT_APP,
+  MICROSOFT_AUTHORIZE_URL,
+  MICROSOFT_IDENTITY,
+  MICROSOFT_TOKEN_URL,
+  TODO_SCOPES,
+  specPath,
+} from '../shared/oauth.ts';
+import { microsoftSetup } from '../shared/setup.ts';
+
+/**
+ * Outlook mail, through Microsoft Graph.
+ *
+ * The REST half of the Microsoft family, and the reason there is no IMAP one
+ * beside it: Microsoft retired basic authentication for Outlook.com IMAP, so an
+ * app password is not a route here the way it is for iCloud, Fastmail, or a
+ * personal Gmail. Graph with a browser sign-in is what works.
+ *
+ * `send_message` is a vendored operation rather than authored code, unlike
+ * Gmail's — Graph composes the message from JSON, so nothing here has to
+ * assemble RFC 2822. What it does not do is attachments: Graph carries those as
+ * base64 inside the message, which is the thing ADR-017 exists to avoid, so the
+ * field is deliberately absent from the vendored body rather than offered and
+ * expensive.
+ */
+export const outlookMail = defineProvider({
+  id: 'outlook_mail',
+  name: 'Outlook Mail',
+  description:
+    'Read, search, file, and send mail in an Outlook or Microsoft 365 mailbox, via Microsoft Graph.',
+  connector: {
+    kind: 'http',
+    // Graph carries its version in the path of the server URL, like Drive and
+    // unlike Sheets. `cli/tools.test.ts` checks this equals the spec's own
+    // `servers[0].url`.
+    base_url: GRAPH_BASE_URL,
+    openapi: specPath('outlook-mail.v1.json'),
+  },
+  auth: {
+    kind: 'oauth',
+    registration: 'manual',
+    app: MICROSOFT_APP,
+    // Declared rather than discovered. An `http` connector has no metadata
+    // document to read — a REST API does not announce where its authorization
+    // server lives — so the two endpoints are part of the manifest.
+    authorize_url: MICROSOFT_AUTHORIZE_URL,
+    token_url: MICROSOFT_TOKEN_URL,
+    scopes: MAIL_SCOPES,
+    revoke_url: 'https://account.live.com/consent/Manage',
+  },
+  identity: MICROSOFT_IDENTITY,
+  setup: microsoftSetup('Outlook Mail', MAIL_SCOPES),
+  // Keyed on the capability name as it is *served* — dots, not underscores.
+  // Graph's operationIds are `me.ListMessages` and nothing strips the `me.`,
+  // because `shortenName` removes the provider id and the provider is not
+  // called "me". A key that misses does not error: it withholds every argument
+  // and reads exactly like working redaction.
+  redact: {
+    // Never `search` or `filter`: a query is content, and "who did I email
+    // about the diagnosis" is the whole message.
+    'me.ListMessages': ['top', 'orderby', 'select'],
+    'me.GetMessages': ['message-id', 'select'],
+    'me.UpdateMessages': ['message-id', 'isRead', 'categories', 'flag', 'importance'],
+    'me.ListMailFolders': ['top', 'orderby', 'select'],
+    'me.messages.ListAttachments': ['message-id', 'top', 'orderby', 'select'],
+    'me.messages.GetAttachments': ['message-id', 'attachment-id', 'select'],
+    // Nothing. The recipients, the subject, and the body are the message.
+    'me.sendMail': ['saveToSentItems'],
+  },
+});

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

@@ -0,0 +1,58 @@
+/** The `oauth_apps` entry every Microsoft provider authorises against. */
+export const MICROSOFT_APP = 'microsoft';
+
+/**
+ * One app registration, five providers.
+ *
+ * Microsoft Graph is a single API behind mail, calendars, contacts, files and
+ * to-do, so unlike Google — where each product has its own client and its own
+ * consent screen — there is one Entra registration here and the providers differ
+ * only in what they ask it for. The token still lands per provider, exactly as
+ * Gmail's and Drive's do: `app` moves where the *client* comes from, never where
+ * the tokens go, so connecting Outlook mail does not silently grant OneDrive.
+ */
+
+/** `common` rather than a tenant id: personal accounts and work accounts both. */
+export const MICROSOFT_AUTHORIZE_URL =
+  'https://login.microsoftonline.com/common/oauth2/v2.0/authorize';
+export const MICROSOFT_TOKEN_URL = 'https://login.microsoftonline.com/common/oauth2/v2.0/token';
+
+/**
+ * Asked for by every provider, and neither reaches a service.
+ *
+ * `offline_access` is not optional and is the one to get wrong: Microsoft issues
+ * no refresh token without it, so the connection authorises cleanly, works for
+ * about an hour, and then stops. That is the same failure Google's
+ * `access_type=offline` exists to prevent, and it is worth naming because the
+ * successful-looking response is what makes it hard to debug an hour later.
+ *
+ * `User.Read` is what the identity probe reads — the account's own name and
+ * address, so a connection can be labelled with whose it is. It reaches no
+ * mailbox, no calendar, and no file.
+ */
+export const MICROSOFT_BASE_SCOPES = ['offline_access', 'User.Read'] as const;
+
+export const MAIL_SCOPES = [...MICROSOFT_BASE_SCOPES, 'Mail.ReadWrite', 'Mail.Send'];
+export const CALENDAR_SCOPES = [...MICROSOFT_BASE_SCOPES, 'Calendars.ReadWrite'];
+export const CONTACTS_SCOPES = [...MICROSOFT_BASE_SCOPES, 'Contacts.Read'];
+export const FILES_SCOPES = [...MICROSOFT_BASE_SCOPES, 'Files.ReadWrite'];
+export const TODO_SCOPES = [...MICROSOFT_BASE_SCOPES, 'Tasks.ReadWrite'];
+
+/**
+ * Whose account this is, for the label a connection is listed under.
+ *
+ * `userPrincipalName` rather than `mail`: a personal Microsoft account often has
+ * no `mail` at all, and a null there would send `connect` to its "which account
+ * is this?" fallback on exactly the accounts this is most useful for.
+ */
+export const MICROSOFT_IDENTITY = {
+  kind: 'http' as const,
+  url: 'https://graph.microsoft.com/v1.0/me',
+  field: 'userPrincipalName',
+};
+
+/** Graph is one host and one version, for all five. */
+export const GRAPH_BASE_URL = 'https://graph.microsoft.com/v1.0';
+
+export const specPath = (file: string): string =>
+  new URL(`../specs/${file}`, import.meta.url).pathname;

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

@@ -0,0 +1,56 @@
+import type { ScopeMeaning } from '../../scopes.ts';
+
+/**
+ * What the Microsoft Graph scopes we ship actually permit, in plain words.
+ *
+ * Vendor knowledge, so it lives with the vendor — the same reasoning as
+ * `../../google/shared/scopes.ts`, and the same confinement: nothing routes on
+ * this, and a scope missing from the table is printed unannotated rather than
+ * mis-described.
+ */
+export const MICROSOFT_SCOPE_MEANINGS: Record<string, ScopeMeaning> = {
+  offline_access: {
+    meaning:
+      'keep the connection working without sending you to a browser again — Microsoft issues no refresh token without it',
+  },
+  'User.Read': {
+    meaning: 'your name and address, so this connection can be labelled with whose it is. No mail, calendar, or files',
+  },
+  // Graph's mail scopes are coarser than Gmail's. There is no equivalent of
+  // `gmail.metadata` or a per-message grant, so reading one message means the
+  // grant reaches every message — which is exactly why `gmail.modify` is on this
+  // list too.
+  'Mail.ReadWrite': {
+    meaning: 'read, file, and modify any message in the mailbox; no permanent delete',
+    broad: true,
+  },
+  'Mail.Read': { meaning: 'read any message in the mailbox' },
+  // Broad for where it lands rather than what it reaches. A sent message leaves
+  // the account, arrives as the person, and cannot be recalled — the same
+  // argument that puts Reddit's three on the broad list.
+  'Mail.Send': {
+    meaning: 'send mail as you — it leaves the account under your name and cannot be recalled',
+    broad: true,
+  },
+  'Calendars.ReadWrite': {
+    meaning: 'read and write every event in every calendar on the account, including invitations sent to others',
+    broad: true,
+  },
+  'Calendars.Read': { meaning: 'read every event in every calendar on the account' },
+  'Contacts.Read': { meaning: 'read the address book. Read-only — nothing here writes a contact' },
+  // Broad, and the only one here that is broad for want of a narrower option.
+  // Google Drive is reached with `drive.file`, which covers files this app made
+  // or the person picked and nothing else; Graph publishes no equivalent, so the
+  // smallest grant that can create a folder is one that reaches every file in
+  // the drive.
+  'Files.ReadWrite': {
+    meaning: 'read and write every file in your OneDrive — Microsoft publishes no per-file equivalent of Google\'s drive.file',
+    broad: true,
+  },
+  'Files.Read': { meaning: 'read every file in your OneDrive' },
+  'Tasks.ReadWrite': {
+    meaning: 'read and write every list and task in Microsoft To Do',
+    broad: true,
+  },
+  'Tasks.Read': { meaning: 'read every list and task in Microsoft To Do' },
+};

package/src/providers/microsoft/shared/setup.ts

@@ -0,0 +1,45 @@
+import { MICROSOFT_APP } from './oauth.ts';
+
+/**
+ * The console walkthrough, shared by all five providers.
+ *
+ * Parameterised by product name and by the permissions that product asks for,
+ * because the registration is one app and the consent is per provider — someone
+ * connecting only To Do should not be told to tick mail permissions.
+ *
+ * A registration of the operator's own, with no broker behind it. Microsoft does
+ * not offer dynamic client registration, so a client has to exist before the
+ * browser opens; until Lanes operates one, that client is theirs. `--own-client`
+ * is not a flag here, it is the only route — which is the `reddit` shape, and
+ * the reason `setup.prompts` carries `scope: shared` entries rather than a
+ * pasted token.
+ */
+export const microsoftSetup = (product: string, permissions: readonly string[]) => ({
+  summary:
+    `${product} authorises in a browser against an app registration of your own in Microsoft Entra. ` +
+    `Registering one is free and takes a few minutes; it is a public client, so there is no secret ` +
+    `to keep. The same registration covers Outlook mail, calendar, contacts, OneDrive and To Do — ` +
+    `you do this once, not once per provider.`,
+  docs: 'https://lanes.sh/docs/link/connect',
+  docs_url: 'https://entra.microsoft.com',
+  steps: [
+    'Open https://entra.microsoft.com and go to Applications → App registrations → New registration.',
+    'Name it "Lanes Link". Under "Supported account types", pick the option that includes personal Microsoft accounts if this is an @outlook.com or @hotmail.com address — the default is work accounts only, and choosing it is what makes a personal account fail at sign-in rather than at registration.',
+    'Under "Redirect URI", choose the platform "Mobile and desktop applications" and enter exactly: http://localhost — no port. Microsoft accepts any port on a loopback redirect for this platform, which is what lets connect listen on whichever one is free.',
+    'Register, then copy the "Application (client) ID" from the overview page. That is the value asked for below.',
+    'Leave "Certificates & secrets" alone. This is a public client: a secret shipped to a program someone runs is not a secret, so none is created and none is asked for.',
+    `Permissions are requested at sign-in rather than configured here, so there is nothing to add under "API permissions" first. ${product} asks for: ${permissions.join(', ')}.`,
+  ],
+  troubleshooting:
+    'AADSTS50011 means the redirect URI does not match: the registration needs the platform "Mobile and desktop applications" with http://localhost, not the "Web" platform, which pins the whole URL including the port. ' +
+    'AADSTS50020 means the account type is wrong — a personal Microsoft account signing in to a registration made for work accounts only. Change it under Authentication → Supported account types and re-run: lanes link connect <provider> --replace.',
+  prompts: [
+    {
+      key: 'client_id',
+      label: 'Application (client) ID',
+      secret: false,
+      scope: 'shared' as const,
+      credential_ref: `${MICROSOFT_APP}/client_id`,
+    },
+  ],
+});