@lanes-sh/link 0.2.2 → 0.3.1

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

@@ -0,0 +1,125 @@
+import { defineProvider } from '#connectivity';
+
+/**
+ * Gmail over IMAP, for the account that cannot use either other route.
+ *
+ * A personal Google account has exactly one way to a mailbox that does not
+ * expire, and this is it. The two alternatives both fail for a reason that is
+ * not about effort:
+ *
+ * - The REST provider (`gmail`) authorises in a browser, and an OAuth client
+ *   left in "Testing" has every refresh token it issues expired after seven
+ *   days. Publishing the client fixes that and is the better answer where it is
+ *   available — see ADR-038 and `docs/detailed/setup/google.md`.
+ * - The key route (`auth.assertion` on `gmail`) does not apply at all. A service
+ *   account has no mailbox of its own, so it can only reach one by acting as
+ *   somebody, and that grant is domain-wide delegation — made in a Workspace
+ *   admin console that a personal account does not have.
+ *
+ * An app password has neither problem. It is issued by the account holder to
+ * themselves, it does not expire, and IMAP asks no authorization server for
+ * anything. What it costs is reach and shape: this is a mailbox over IMAP and
+ * SMTP, so it is the mail capability set rather than Gmail's API — no labels
+ * vocabulary, no threads resource, no drafts. Searching, reading, flagging,
+ * moving and sending, which is most of what a mailbox is for.
+ *
+ * The mirror image of `../shared/service-account.ts`, and deliberately so: that
+ * one covers Workspace and not personal accounts, this one covers personal
+ * accounts and not Workspace. Google turned off basic authentication for
+ * Workspace in March 2025, and an administrator can disable app passwords
+ * outright, so an account under a domain should take one of the other two.
+ *
+ * A separate manifest rather than a route on `gmail` because a manifest has one
+ * connector, and IMAP is a different protocol from HTTPS — the same reason
+ * iCloud is three providers rather than one. It also makes the policy line
+ * separable: `gmail_imap.*` can be allowed without granting the REST surface,
+ * or the other way round.
+ */
+export const gmailImap = defineProvider({
+  id: 'gmail_imap',
+  name: 'Gmail (IMAP)',
+  description:
+    'Read, search, and send mail in a personal Gmail mailbox over IMAP and SMTP, with an app password that does not expire.',
+  connector: {
+    kind: 'imap',
+    host: 'imap.gmail.com',
+    port: 993,
+    smtp: {
+      host: 'smtp.gmail.com',
+      port: 587,
+      starttls: true,
+      // Gmail's limit is 25 MB for the whole encoded message rather than the
+      // 20 MB default, and the send path derives the usable weight of the files
+      // from it. Declaring the real number is what makes an oversized message
+      // refused before dialling rather than part-way through DATA.
+      max_message_bytes: 25 * 1024 * 1024,
+    },
+  },
+  // Not a choice. `defineProvider` refuses anything else on an imap connector,
+  // because every mail host that matters issues an app password and expects it
+  // over Basic — and Gmail's OAuth path belongs to the REST provider.
+  auth: { kind: 'basic' },
+  // No `app`: this is one provider rather than a family, so the credential
+  // lands at `gmail_imap/<connection>` and is shared with nothing. An app
+  // password is issued per app rather than per account, so there would be
+  // nothing to share it with even if there were siblings.
+  identity: { kind: 'connector' },
+  setup: {
+    summary:
+      'Gmail over IMAP uses an app password — a sixteen-character password you issue to yourself, ' +
+      'which is not your Google account password and does not expire. Nothing is authorised in a ' +
+      'browser and nothing has to be re-approved later. This is the personal-account route: ' +
+      'Google turned off basic authentication for Workspace accounts in March 2025, and a Workspace ' +
+      'administrator can disable app passwords for the whole domain.',
+    docs: 'docs/detailed/setup/google.md',
+    docs_url: 'https://support.google.com/accounts/answer/185833',
+    steps: [
+      'Two-Step Verification has to be on. Without it Google does not offer app passwords at all, and the page below returns "the setting you are looking for is not available for your account" rather than saying why. Turn it on at https://myaccount.google.com/signinoptions/twosv.',
+      'Open https://myaccount.google.com/apppasswords and create one. Name it "Lanes Link" — the name is the only way to revoke this one later without cutting off your other devices.',
+      'Copy the sixteen characters. Google shows them once, in four groups of four; the spaces are cosmetic and it is accepted either way.',
+      'You are asked for your full address next, which is the one you sign in with, ending @gmail.com.',
+      'IMAP is on by default. If a login is refused with a mailbox error rather than an authentication error, check Gmail → Settings → See all settings → Forwarding and POP/IMAP → IMAP access.',
+    ],
+    // What a transport cannot say for itself, because it must not know which
+    // vendor it is talking to. The first sentence is the mistake this route
+    // actually produces: an app password looks enough like a password that the
+    // account password gets pasted instead, and IMAP reports both identically.
+    troubleshooting:
+      'For Gmail this is almost always a Google account password used where an app password belongs, ' +
+      'or an account without Two-Step Verification — app passwords do not exist without it. Generate ' +
+      'one at https://myaccount.google.com/apppasswords and re-run: lanes link connect gmail_imap --replace.',
+    prompts: [
+      {
+        key: 'username',
+        label: 'Google account (the full email address)',
+        secret: false,
+        scope: 'connection' as const,
+        field: 'username' as const,
+      },
+      {
+        key: 'password',
+        label: 'App password (sixteen characters)',
+        secret: true,
+        scope: 'connection' as const,
+        field: 'password' as const,
+      },
+    ],
+  },
+  // The mail capability set, so the same reasoning as `icloud_mail` applies
+  // verbatim: opted back in one key at a time, everything unlisted withheld.
+  redact: {
+    // Never the search terms — a query is content, and "who did I email about
+    // the diagnosis" is the whole message.
+    search_messages: ['mailbox', 'limit', 'unseen', 'flagged'],
+    get_message: ['mailbox', 'uid', 'include_body'],
+    mark_messages: ['mailbox', 'add_flags', 'remove_flags'],
+    // `destination_flag` alongside `destination`: two spellings of the same
+    // fact, and keeping only one means a junk move logs with no destination.
+    move_messages: ['mailbox', 'destination', 'destination_flag'],
+    // Nothing. The recipients and the body are the message, and `attachments`
+    // may literally contain a file. What was attached is recorded by the send
+    // path itself through `audit.annotate` — filename, size, type, SHA-256 and
+    // origin. Identifiers, not content.
+    send_message: [],
+  },
+});

package/src/providers/google/index.ts

@@ -1,10 +1,11 @@
-/** Google's nine providers. Each folder holds all of its own vendor knowledge. */
+/** Google's ten 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 { gmailImap } from './gmail-imap/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

@@ -24,10 +24,18 @@ export const GOOGLE_APP = 'google';
  * 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.
+ * console, and no scope list to transcribe. 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.
+ *
+ * What it does *not* buy, and used to claim to: escape from the seven-day
+ * refresh-token expiry. That expiry is a property of the client's publishing
+ * status rather than of its verification, and a client under review has the
+ * status it has — so a connection made this way is re-authorised weekly until
+ * the review lands, exactly like one made against a client of the operator's
+ * own that was left in "Testing". The way around it is not a different client.
+ * It is `auth.assertion`: a key does not expire because nothing consented, and
+ * `./service-account.ts` is that route.
  */
 const BROKER_ORIGIN = 'https://api.lanes.sh';
 const BROKER_PATH = '/v1/auth/link/google';
@@ -62,8 +70,12 @@ export const GOOGLE_OAUTH = {
   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.
+  // not spread it, which is what keeps them bring-your-own.
+  //
+  // That is now a choice rather than a constraint. ADR-040 made a broker legal
+  // on an mcp connector that names its own endpoints, so these two could follow
+  // Slack — what stops them is that nobody has established which client Google
+  // would have us use for its MCP servers, not that the machinery refuses.
   broker: GOOGLE_BROKER,
 } as const;
 

package/src/providers/google/shared/service-account.ts

@@ -0,0 +1,110 @@
+import { GOOGLE_APP } from './oauth.ts';
+
+/**
+ * The other way into a Google account: a key, instead of a browser.
+ *
+ * Google issues service accounts, and a service account holds a private key
+ * that does not expire. It is the answer to the one complaint the browser flow
+ * cannot fix — that a client left in "Testing" has its refresh tokens expired
+ * after seven days, so every connection has to be re-approved weekly until
+ * verification lands. A key is not subject to that, or to any other policy the
+ * issuer applies to consent, because nobody consented.
+ *
+ * What it costs is reach, and the cost is different per product, which is why
+ * `delegation` is a parameter rather than a constant. A service account is an
+ * identity in its own right: it has a Drive, and a calendar, and no mailbox and
+ * no contacts. So Drive, Sheets, Docs and Calendar work by *sharing* something
+ * with its address, and Gmail, Contacts and Tasks work only if a Workspace
+ * administrator lets the key act as a person. A personal Google account has no
+ * administrator, so for those three there is no key route at all and the
+ * walkthrough says so rather than letting someone find out later.
+ */
+
+/** Where the key lives. One file per profile, covering every Google provider. */
+export const GOOGLE_KEY_REF = `${GOOGLE_APP}/service_account_key`;
+
+const SHARE_HINT: Record<string, string> = {
+  Drive: 'a folder (Share → paste the address → Editor)',
+  Sheets: 'a spreadsheet (Share → paste the address → Editor)',
+  Docs: 'a document (Share → paste the address → Editor)',
+  Calendar:
+    'a calendar (Settings for that calendar → "Share with specific people" → paste the address)',
+};
+
+/**
+ * Where a personal account should go instead, for the products that have
+ * somewhere.
+ *
+ * Only Gmail does. A key needs delegation for mail, contacts and task lists
+ * alike, and delegation needs an administrator — but mail is the one Google
+ * still serves over a protocol that takes a password, so `gmail_imap` is a real
+ * answer rather than a consolation. Contacts and Tasks have none, and saying so
+ * plainly beats sending somebody to look.
+ */
+export const googleServiceAccount = (
+  product: string,
+  scopes: readonly string[],
+  delegation: 'optional' | 'required',
+  apis: readonly string[],
+  instead?: string,
+) => ({
+  method: 'service_account',
+  label: 'Service account key',
+  delegation,
+  key_ref: GOOGLE_KEY_REF,
+  reach:
+    delegation === 'optional'
+      ? `a JSON key that never expires, and no browser. Reaches only what you share with the ` +
+        `key's own address, so nothing in the account moves until you share it.`
+      : `a JSON key that never expires, and no browser. ${product} has nothing that belongs to ` +
+        `a key, so this needs a Google Workspace administrator to let it act as you — a personal ` +
+        `Google account cannot do it` +
+        (instead ? `, and wants ${instead} instead.` : '.'),
+  subject_label:
+    delegation === 'optional'
+      ? 'Google account to act as, if an administrator has granted it'
+      : 'Google account to act as',
+  setup: {
+    summary:
+      delegation === 'optional'
+        ? `${product} can authenticate with a service account key instead of signing in. The key ` +
+          `does not expire, so this is connected once and stays connected. It reaches only what ` +
+          `is shared with it, which is the trade: you pick what it can see, one resource at a time.`
+        : `${product} can authenticate with a service account key instead of signing in. The key ` +
+          `does not expire — but a key has no mailbox, contacts or task lists of its own, so this ` +
+          `route works only where a Google Workspace administrator has authorised the key to act ` +
+          `as a user in their domain. On a personal Google account, use the browser instead` +
+          (instead ? `, or ${instead}, which is an app password over IMAP and does not expire either.` : '.'),
+    docs: 'docs/detailed/setup/google.md',
+    docs_url: 'https://console.cloud.google.com/iam-admin/serviceaccounts',
+    steps: [
+      'Create or pick a project at https://console.cloud.google.com',
+      `Enable the APIs:\n       gcloud services enable ${apis.join(' ')} --project=YOUR_PROJECT\n       Without gcloud: APIs & Services → Library, and search for each by name.`,
+      'IAM & Admin → Service Accounts → Create service account. Name it "Lanes Link". Grant it no project roles — the roles page governs Google Cloud resources, and nothing here is one.',
+      'Open the account → Keys → Add key → Create new key → JSON. It downloads once. You are asked for the path to that file next; its contents go to the credential store and the file itself is not read again.',
+      ...(delegation === 'required'
+        ? [
+            'THIS PRODUCT NEEDS DOMAIN-WIDE DELEGATION, which only a Google Workspace administrator can grant. Copy the service account\'s numeric "Unique ID" (the client ID, not the email) from its Details tab.',
+            `In the Workspace Admin console → Security → Access and data control → API controls → Domain-wide delegation → Add new. Paste that client ID, and paste this scope list exactly:\n       ${scopes.join(',\n       ')}\n       All of them, comma-separated, in one field. A partial list is refused the same way a missing one is, and the refusal does not say which scope was short.`,
+            'Delegation can take a few minutes to take effect. If the first connect is refused with "unauthorized_client", wait and run it again — nothing was stored.',
+          ]
+        : [
+            `Share what you want reachable with the service account's email address — it ends in .iam.gserviceaccount.com and is printed once the key is stored. For ${product} that means ${SHARE_HINT[product] ?? 'the resource itself'}.`,
+            'Nothing else in the account is reachable, including files the same person owns. That is the point of this route, and it is also the thing to remember when something is "missing" — it has not been shared yet.',
+            'A Workspace administrator can instead grant domain-wide delegation, which lets the key act as a user and reach everything they can. The connect prompt asks which account to act as; leaving it blank means the key acts as itself.',
+          ]),
+    ],
+    prompts: [
+      {
+        key: 'service_account_key',
+        label: 'Path to the downloaded JSON key (or paste its contents)',
+        // Read from a path in the ordinary case, so this is not a secret typed
+        // into a terminal — but it may be pasted, and a pasted private key must
+        // not land in scrollback.
+        secret: true,
+        scope: 'shared' as const,
+        credential_ref: GOOGLE_KEY_REF,
+      },
+    ],
+  },
+});

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

@@ -40,6 +40,21 @@ export const googleSetup = (
     summary: `${product} signs in with Google. By default it authorises against the OAuth client Lanes operates, so there is nothing to register and no client secret on this machine — the code is exchanged for a token by the Lanes API, which holds that secret. Pass --own-client to register a client of your own instead; the steps below are that path, asked once per profile and then covering every Google account you connect.`,
     docs: 'docs/detailed/setup/google.md',
     docs_url: 'https://console.cloud.google.com/auth',
+    // AUDIENCE leads with Internal, and the ordering is the point rather than a
+    // preference. The seven-day `invalid_grant` everyone hits is a property of
+    // publishing status, and an Internal app has no publishing status to have —
+    // so it also has no expiry, no verification question, no unverified-app
+    // warning, no test-user list, and no scope registration. Steering a
+    // Workspace user to External costs them every one of those, to buy reach
+    // they do not want: Internal admits only their own domain, which is the
+    // whole set of accounts they were going to connect.
+    //
+    // What it cannot be is the only path. "Internal" is Google's word for
+    // "inside my Workspace organisation", not "private to me", and the option
+    // is simply absent on a project with no organisation behind it. So a
+    // personal @gmail.com still needs External and still has to publish, and
+    // the steps say which half applies to whom rather than making everyone read
+    // both.
     steps: [
       ...(options.preview
         ? [
@@ -56,11 +71,14 @@ export const googleSetup = (
       }\n       Without gcloud: APIs & Services → Library, and search for each by name.`,
       'The rest is under Google Auth Platform — https://console.cloud.google.com/auth — in this order:',
       '  BRANDING — app name and a support email. Seen by nobody but you.',
-      '  AUDIENCE — User type: EXTERNAL (even with a Workspace domain: "Internal" admits only that one domain, so a mix of personal and Workspace accounts needs External). Add every account you will connect under "Test users". LEAVE the status as "Testing".',
-      `  DATA ACCESS — where scopes live now. Add:\n       ${scopes.join('\n       ')}\n       Note drive.file is filed under "sensitive" rather than "restricted", so it appears in a different section of that page.`,
+      '  AUDIENCE — User type, and this is the step that decides how much of the rest you do.\n       INTERNAL, if the project sits in a Google Workspace organisation and every account you will connect is on that domain. An Internal app has no publishing status at all — so no seven-day expiry, no verification, no test-user list, no unverified-app warning screen, and no scopes to register. Skip to CLIENTS.\n       EXTERNAL, for a personal @gmail.com, or a mix of personal and Workspace accounts. Internal is not offered without a Workspace organisation, and admits only your own domain. Add every account you will connect under "Test users", then do the two steps below.',
+      '  AUDIENCE, again — EXTERNAL ONLY: PUBLISH the app. This is the setting that decides whether your connections survive the week, and it is not the same thing as verification: a client left in "Testing" has every refresh token it issues expired after exactly seven days, and one set to "In production" does not, review pending or not. Internal apps have no publishing status, which is why they never expire.',
+      `  DATA ACCESS — EXTERNAL ONLY. Where scopes live now. Add:\n       ${scopes.join('\n       ')}\n       Note drive.file is filed under "sensitive" rather than "restricted", so it appears in a different section of that page. An Internal app does not need this: it authorises scopes that were never registered here, so the page can stay empty.`,
       '  CLIENTS — Create OAuth client → type: DESKTOP APP. Google\'s docs say "Web application" with a redirect URI for Claude or Antigravity, because they assume the agent host runs the OAuth. Here the CLI does, on a loopback port — which is also why this stays Desktop even when the server runs on Cloud Run.',
       'Copy the client ID and secret — you are asked for them next.',
-      'Not publishing is deliberate: these are restricted scopes, and publishing them means Google verification with a CASA assessment taking months. Testing needs none. The cost is that refresh tokens expire after 7 days, so expect to re-run "lanes link connect" weekly — "lanes link doctor" says which are stale.',
+      'EXTERNAL ONLY — what publishing unverified costs, so it is a decision rather than a surprise: everyone you connect sees a "Google hasn\'t verified this app" screen and has to click through Advanced, and the project gains a cap of 100 new users granted these scopes. That cap is for the lifetime of the project and cannot be reset — which does not matter for a client only you use, and matters a great deal for one you intend to hand out. None of this applies to an Internal app.',
+      'EXTERNAL ONLY — verification itself is the other path and a much longer one: restricted scopes mean a review with a security assessment measured in months. It is worth starting and not worth waiting on, since publishing above removes the weekly re-authorisation today. If you have a Workspace domain, Internal skips this question entirely.',
+      'If none of that suits — an organisation that forbids publishing, or a client that must stay in Testing — connect with a service account key instead. It does not expire at all: lanes link connect ' + product.toLowerCase().split(' ')[0] + ' --auth service_account',
     ],
     prompts: [
       {

package/src/providers/google/sheets/index.ts

@@ -1,5 +1,6 @@
 import { defineProvider } from '#connectivity';
 import { DRIVE_IDENTITY, GOOGLE_APP, GOOGLE_OAUTH, specPath } from '../shared/oauth.ts';
+import { googleServiceAccount } from '../shared/service-account.ts';
 import { googleSetup } from '../shared/setup.ts';
 import { SHEETS_HINTS } from './hints.ts';
 import { SHEETS_REDACT } from './redact.ts';
@@ -60,6 +61,7 @@ export const sheets = defineProvider({
     app: GOOGLE_APP,
     scopes: SHEETS_SCOPES,
     ...GOOGLE_OAUTH,
+    assertion: googleServiceAccount('Sheets', SHEETS_SCOPES, 'optional', ['sheets.googleapis.com', 'drive.googleapis.com']),
   },
   identity: DRIVE_IDENTITY,
   setup: googleSetup('Sheets', SHEETS_SCOPES, {

package/src/providers/google/tasks/index.ts

@@ -1,5 +1,6 @@
 import { defineProvider } from '#connectivity';
 import { GOOGLE_APP, GOOGLE_OAUTH, specPath } from '../shared/oauth.ts';
+import { googleServiceAccount } from '../shared/service-account.ts';
 import { googleSetup } from '../shared/setup.ts';
 import { TASKS_REDACT } from './redact.ts';
 
@@ -47,6 +48,7 @@ export const tasks = defineProvider({
     app: GOOGLE_APP,
     scopes: TASKS_SCOPES,
     ...GOOGLE_OAUTH,
+    assertion: googleServiceAccount('Tasks', TASKS_SCOPES, 'required', ['tasks.googleapis.com']),
   },
   setup: googleSetup('Tasks', TASKS_SCOPES, { apis: ['tasks.googleapis.com'] }),
   redact: TASKS_REDACT,

package/src/providers/identity/provider.ts

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+import { defineLocalProvider, type ProviderDefinition } from '#connectivity';
+import type { IdentityEntry } from '#profile';
+
+/**
+ * `identity` — who the owner is, for anything written as them.
+ *
+ * **Read-only by construction, for the same reason `setup` is.** ADR-007 keeps
+ * configuration mutation off the MCP surface, and this block *is* configuration:
+ * an agent that could rewrite whose name it signs with would be rewriting the
+ * one fact that stops it signing wrong. Declaring it is the owner's, in a
+ * terminal. So there is one capability, it is a read, and `provider.test.ts`
+ * asserts the capability list holds nothing else.
+ *
+ * Reporting it authorises nothing, which is the ADR-019 argument again. A name
+ * and an address are disclosed by the first message of any mailbox this endpoint
+ * serves — a caller holding a grant on a mail connection already has them —
+ * so withholding them here while serving the mailbox would be theatre. The
+ * difference is that reading them *here* means not having to guess, and a guess
+ * is what this exists to replace.
+ *
+ * Why it is its own provider rather than a third section of `setup_overview`:
+ * policy. `identity.*` is a grant an owner can give or withhold on its own, so
+ * an endpoint can describe what is connected without naming its owner, or name
+ * its owner without describing what is connected. Folding it into `setup` would
+ * have made those one decision, and they are not.
+ *
+ * `identity.list` is clean against the seven patterns in
+ * `dispatch/control-plane.test.ts`. So is `identity` as a prefix. Neither is a
+ * cosmetic name.
+ */
+
+export interface IdentityProviderOptions {
+  /**
+   * Which profile this instance serves.
+   *
+   * Stamped at construction for the reason recorded on `SetupProviderOptions`:
+   * `makeHandler` strips `profile` off the arguments before dispatch and
+   * `ProviderContext` does not carry it, so a handler cannot learn it. One
+   * registry is built per profile, so each instance gets its own.
+   */
+  readonly profile: string;
+  /**
+   * Which target it is serving, for the command in the empty case.
+   *
+   * Needed for the same reason `setup`'s plans need it: `--profile` and
+   * `--target` are required flags (ADR-037), and a command handed to an agent
+   * without both is a paste that refuses. An agent pastes what it is given.
+   */
+  readonly target?: string;
+  /**
+   * What that profile declares, in declaration order.
+   *
+   * A snapshot rather than a function, unlike `setup`'s `reachable`. That one
+   * has to be re-evaluated per call because policy is; this is config, and the
+   * registry holding it is rebuilt whenever config is re-read — so an entry
+   * added by the CLI is served after the next reload, exactly as a new
+   * connection is, and a function here would only imply a freshness it could
+   * not deliver.
+   */
+  readonly entries?: readonly IdentityEntry[];
+}
+
+export function createIdentityProvider(options: IdentityProviderOptions): ProviderDefinition {
+  const entries = options.entries ?? [];
+
+  return defineLocalProvider({
+    id: 'identity',
+    name: 'Identity',
+    version: '1.0.0',
+    description:
+      'The names, addresses, and handles this profile declares for its owner, and a note on ' +
+      'when each applies. Read-only: what is declared is set in the CLI, because an agent able ' +
+      'to change whose name it signs with could change the one fact that stops it signing wrong.',
+
+    configSchema: z.object({}),
+    connectionSchema: z.object({}),
+
+    bundles: [
+      {
+        name: 'read',
+        description: 'Read the declared identity. There is no write bundle, by design.',
+        oauth_scopes: [],
+        capabilities: ['list'],
+        default: true,
+      },
+    ],
+
+    capabilities: [
+      {
+        kind: 'tool',
+        name: 'list',
+        title: 'Who the owner is, in this profile',
+        description:
+          'The names, addresses, and handles this profile declares for its owner, each with a ' +
+          'note on when it applies. Call this before writing as them — signing a message, ' +
+          'addressing one, choosing an account to act as — rather than inferring one from ' +
+          'the conversation. A profile may declare several of a kind deliberately.',
+        inputSchema: z.object({}),
+        // No arguments to redact.
+        async handler(_input, _handlerContext) {
+          return {
+            content: [{ type: 'text', text: render(options.profile, options.target, entries) }],
+          };
+        },
+      },
+    ],
+  });
+}
+
+/**
+ * Grouped by kind, in order of first appearance, and self-describing per line.
+ *
+ * Grouped because the failure this exists to prevent is a name used where an
+ * address was wanted, and adjacency is most of what stops that. The kind is
+ * repeated on every line anyway rather than written once as a heading: a line
+ * lifted out of this block on its own then still says what it is, and a model
+ * quoting one line is exactly what happens next.
+ *
+ * Order within a kind is declaration order, which is the owner's ranking.
+ */
+function render(
+  profile: string,
+  target: string | undefined,
+  entries: readonly IdentityEntry[],
+): string {
+  if (entries.length === 0) {
+    // Both flags, spelled out. They are required (ADR-037), so a command
+    // missing either is one the owner pastes and watches refuse — and this is
+    // handed to an agent, which relays it verbatim.
+    const where = `--profile ${profile}${target ? ` --target ${target}` : ''}`;
+    return (
+      `Profile "${profile}" declares no identity.\n\n` +
+      'Nothing here says what name or address to use, so do not invent one — ask. ' +
+      `The owner declares them with \`lanes link identity add <kind> <value> ${where}\`.`
+    );
+  }
+
+  const kinds = [...new Set(entries.map((entry) => entry.kind))];
+  const ordered = kinds.flatMap((kind) => entries.filter((entry) => entry.kind === kind));
+
+  const kindWidth = Math.max(...ordered.map((entry) => entry.kind.length));
+  const valueWidth = Math.max(...ordered.map((entry) => entry.value.length));
+
+  const lines = ordered.map((entry) => {
+    const head = `  ${entry.kind.padEnd(kindWidth)}  ${entry.value}`;
+    return entry.note ? `${head.padEnd(kindWidth + valueWidth + 4)}  — ${entry.note}` : head;
+  });
+
+  // Said here rather than left to the reader because "several names" is
+  // otherwise ambiguous in the one direction that matters: a model handed two
+  // with no ranking picks by position anyway, and may as well be told that
+  // position is what it means.
+  const several = kinds.some((kind) => entries.filter((entry) => entry.kind === kind).length > 1);
+
+  return [
+    `Identity for profile "${profile}".`,
+    '',
+    ...lines,
+    '',
+    several
+      ? 'Where a kind holds more than one, the first is the default and the notes say when to ' +
+        'prefer another. If none of them fits what you are doing, ask rather than combining them.'
+      : 'Use these as written. If what you need is not here, ask rather than inferring it.',
+  ].join('\n');
+}

package/src/providers/index.ts

@@ -6,6 +6,7 @@ import { github } from './github/index.ts';
 import { drive } from './google/drive/index.ts';
 import { driveMcp } from './google/drive-mcp/index.ts';
 import { gmail } from './google/gmail/index.ts';
+import { gmailImap } from './google/gmail-imap/index.ts';
 import { gmailMcp } from './google/gmail-mcp/index.ts';
 import { sheets } from './google/sheets/index.ts';
 import { tasks } from './google/tasks/index.ts';
@@ -59,6 +60,7 @@ export const PROVIDERS: readonly (ProviderManifest | ProviderDefinition)[] = [
   calendar,
   tasks,
   contacts,
+  gmailImap,
   gmailMcp,
   driveMcp,
   icloudMail,
@@ -87,6 +89,7 @@ export {
   drive,
   driveMcp,
   gmail,
+  gmailImap,
   gmailMcp,
   sheets,
   tasks,

package/src/providers/owner.ts

@@ -1,5 +1,5 @@
 /**
- * The owner layer — memory, skills, vault.
+ * The owner layer — memory, skills, vault, setup, identity.
  *
  * Three providers that hold no third-party account: no OAuth, no vendor API, no
  * rate limit anyone else imposes. They are ordinary `defineLocalProvider`
@@ -19,7 +19,14 @@
  * read-only by construction — see ADR-019 for why describing setup is not one
  * of ADR-007's control-plane exclusions.
  *
- * The ids `memory`, `skills`, `vault`, and `setup` are reserved (`RESERVED_PROVIDER_IDS`)
+ * `identity` is the fifth and holds no account either. It says who the owner is
+ * — the names and addresses to write as them — and is read-only for the reason
+ * `setup` is: what it reports is configuration, and configuration is changed in
+ * the CLI. It is a provider of its own rather than a section of `setup` so that
+ * naming the owner and describing what is connected are two policy decisions
+ * instead of one.
+ *
+ * The ids `memory`, `skills`, `vault`, `setup`, and `identity` are reserved (`RESERVED_PROVIDER_IDS`)
  * and still refused by default — the registry has to be built with
  * `allowReserved` to hold them, so a third-party provider cannot claim a
  * namespace whose policy rules would then mean something else.
@@ -29,6 +36,7 @@ export { memoryProvider, memoryStorage, assertEntryId, type MemoryEntry } from '
 export { createSkillsProvider, type SkillsProviderOptions } from './skills/provider.ts';
 export { createVaultProvider, type VaultProviderOptions } from './vault/provider.ts';
 export { createSetupProvider, type SetupProviderOptions } from './setup/provider.ts';
+export { createIdentityProvider, type IdentityProviderOptions } from './identity/provider.ts';
 export { planAll, planFor, type PlanContext, type ProviderPlan } from './setup/plan.ts';
 // The vault's *store* is not here: it is `#secrets`, beside the system
 // credential store it must never become. What lives in `./vault/` is the

package/src/providers/scopes.ts

@@ -1,5 +1,6 @@
 import { GOOGLE_SCOPE_MEANINGS } from './google/shared/scopes.ts';
 import { LINEAR_SCOPE_MEANINGS } from './linear/scopes.ts';
+import { SLACK_SCOPE_MEANINGS } from './slack/scopes.ts';
 
 /**
  * What a scope actually permits, contributed by the provider that requests it.
@@ -23,4 +24,5 @@ export interface ScopeMeaning {
 export const SCOPE_MEANINGS: Record<string, ScopeMeaning> = {
   ...GOOGLE_SCOPE_MEANINGS,
   ...LINEAR_SCOPE_MEANINGS,
+  ...SLACK_SCOPE_MEANINGS,
 };