@lanes-sh/link 0.2.2 → 0.3.0

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,
 };

package/src/providers/setup/plan.ts

@@ -1,5 +1,5 @@
 import type { ProviderManifest } from '#connectivity';
-import { setupRequirements, type SetupRequirement } from '#connectivity';
+import { hasOwnClientPath, setupRequirements, type SetupRequirement } from '#connectivity';
 
 /**
  * What connecting a provider involves, assembled from its manifest.
@@ -68,10 +68,22 @@ export interface ProviderPlan {
   readonly clientOperator?: string;
   /** The line that opts out of it and registers one of your own instead. */
   readonly ownClientCommand?: string;
+  /** What `--auth pasted_token` asks for, where that is a way in. */
+  readonly pastedCredential?: string;
+  /** The line that takes that way in. */
+  readonly tokenCommand?: string;
 }
 
 export interface PlanContext {
   readonly profile: string;
+  /**
+   * Which target's stores the emitted command should act on.
+   *
+   * Stamped like `profile` is, and for a stronger reason: a connection's
+   * credential lives in one target's store, so a `connect` that lands in the
+   * wrong one authorises an account the endpoint asking for it cannot read.
+   */
+  readonly target: string;
   /** Every configured connection this caller may see, as `provider.id`. */
   readonly connections: readonly string[];
   /**
@@ -88,21 +100,22 @@ export function planFor(
   context: PlanContext,
   connectionId?: string,
 ): ProviderPlan {
-  const { requirements, needsId, brokered } = setupRequirements(
+  const { requirements, needsId, brokered, pastedCredential } = setupRequirements(
     manifest,
     connectionId,
-    context.profile,
+    { profile: context.profile, target: context.target },
     { ...(context.ownClients ? { ownClients: context.ownClients } : {}) },
   );
 
   const connected = context.connections.filter((key) => key.startsWith(`${manifest.id}.`));
 
-  // `--profile` always, never conditionally. One endpoint serves every profile,
-  // and the shell this command is pasted into may default to a different one —
-  // which is exactly what `resolveSelection`'s "never a silent pick" rule
-  // exists to prevent.
+  // Both, always, never conditionally. One endpoint serves every profile and
+  // each profile may declare several targets, and the shell this is pasted into
+  // supplies neither — nothing but the command line does. An emitted command
+  // missing either is one that refuses, or worse, writes a credential into a
+  // store the endpoint that asked for it does not read.
   const command =
-    `lanes link connect ${manifest.id} --profile ${context.profile}` +
+    `lanes link connect ${manifest.id} --profile ${context.profile} --target ${context.target}` +
     (needsId ? ' --id <name>' : connectionId ? ` --id ${connectionId}` : '');
 
   return {
@@ -119,13 +132,22 @@ export function planFor(
     needsId,
     command,
     brokered,
+    ...(pastedCredential
+      ? { pastedCredential, tokenCommand: `${command} --auth pasted_token` }
+      : {}),
     ...(brokered && manifest.auth.kind === 'oauth' && manifest.auth.broker
       ? {
           clientOperator: manifest.auth.broker.operator,
           // The steps stay in `steps` either way. A renderer decides whether to
           // show a console walkthrough for a path nobody has asked for; the
           // plan's job is to say the path exists and what opens it.
-          ownClientCommand: `${command} --own-client`,
+          //
+          // Offered only where the manifest actually describes a client to
+          // register. Slack's does not — it asks for a token, never for a
+          // client id and secret — and `resolveOAuthClient` refuses the flag on
+          // exactly that ground, so printing it here would be handing somebody
+          // a command that answers back with "there is no such path".
+          ...(hasOwnClientPath(manifest) ? { ownClientCommand: `${command} --own-client` } : {}),
         }
       : {}),
   };

package/src/providers/setup/provider.ts

@@ -47,6 +47,13 @@ export interface SetupProviderOptions {
    * here — one registry is built per profile, so each instance gets its own.
    */
   readonly profile: string;
+  /**
+   * Which target this instance's stores came from.
+   *
+   * Stamped at construction for the same reason `profile` is, and it travels no
+   * further than the commands this provider emits — nothing here opens a store.
+   */
+  readonly target: string;
   /** Sibling profile names on this endpoint. Names only; already at `/health`. */
   readonly profiles?: readonly string[];
   /**
@@ -79,6 +86,7 @@ export function createSetupProvider(options: SetupProviderOptions): ProviderDefi
 
   const context = () => ({
     profile: options.profile,
+    target: options.target,
     connections: reachable().map((connection) => connection.key),
     ...(options.ownClients ? { ownClients: options.ownClients } : {}),
   });
@@ -309,6 +317,21 @@ function renderProvider(plan: ProviderPlan): string {
     );
   }
 
+  // An alternative, said as one. It is not a value the command above needs, and
+  // rendering it beside the requirements — which is what it did before there
+  // was anywhere else to put it — reads as a second mandatory step in a setup
+  // whose whole selling point is that it has none.
+  if (plan.tokenCommand && plan.pastedCredential) {
+    lines.push(
+      '',
+      'If the browser path is refused — a workspace that has not approved this app, which an ' +
+        `admin decides — the same command takes --auth pasted_token and asks for the ` +
+        `${plan.pastedCredential}:`,
+      `  ${plan.tokenCommand}`,
+      '  The console steps for obtaining one are in the setup documentation above.',
+    );
+  }
+
   if (plan.browser) {
     lines.push(
       '',

package/src/providers/slack/index.ts

@@ -1,68 +1,116 @@
 import { defineProvider } from '#connectivity';
 import { SLACK_REDACT } from './redact.ts';
+import { SLACK_APP, SLACK_BROKER, SLACK_SCOPES } from './oauth.ts';
 
 /**
  * Slack, through the server Slack runs.
  *
- * The only provider here whose vendor has closed every door but one. Slack's
- * MCP server does not offer Dynamic Client Registration — their documentation
- * says so outright — and a client of your own cannot work either: Slack
- * requires an HTTPS redirect URI, and `connect` listens on `http://127.0.0.1`
- * on a port the kernel picks. There is no proxy, tunnel, or flag that makes a
- * loopback listener HTTPS. A broker would answer it and `defineProvider`
- * refuses one on an mcp connector, because the SDK owns that exchange.
+ * Slack does not offer Dynamic Client Registration and is not going to: it
+ * would let a client authenticate a user without an app existing, and on
+ * Enterprise Grid an admin approves each app first. So a client has to be
+ * pre-registered — and the question this provider used to answer wrongly is
+ * *whose*.
  *
- * What is left is the user token the Slack app mints when you install it, sent
- * as `Authorization: Bearer`. Slack supports that path deliberately; it is the
- * arrangement their own docs describe for a client that cannot register. See
- * ADR-033.
+ * It was the operator's: create an app, transcribe sixteen user-token scopes,
+ * install it, paste the `xoxp-` it mints. That was the honest shape of it only
+ * while the alternative was believed impossible. It was not. Every client that
+ * reaches Slack without a console visit does the same thing — registers one app
+ * and ships its id — and this now does too, with the secret behind the broker
+ * ADR-028 already built for Google and the redirect on a port Slack has been
+ * told about. ADR-040 records what changed and why the reasoning in ADR-033 no
+ * longer holds.
  *
- * Unlike GitHub, this does cost a console visit — creating a Slack app is the
- * only way to get a user token at all, and no amount of implementation work on
- * this side removes it. The setup block is therefore longer than any other here
- * except Google's, and that is the honest shape of it.
+ * The paste is still here, behind `--auth pasted_token`. A workspace whose admin has not
+ * approved the Lanes app cannot use the flow above, and that is not a decision
+ * the person running this command can make.
  */
 export const slack = defineProvider({
   id: 'slack',
   name: 'Slack',
   description: 'Messages, threads, channels, files, and canvases, via Slack\'s official MCP server.',
   connector: { kind: 'mcp', endpoint: 'https://mcp.slack.com/mcp' },
-  auth: { kind: 'bearer' },
   /**
-   * The person, not the workspace, and the distinction is load-bearing.
+   * An mcp connector that names its own endpoints, which is what takes it off
+   * the SDK's flow and onto the one this repository drives.
    *
-   * `settleIdentity` matches a resolved account against existing connections
-   * to decide whether this is a reconnect or a new account. Labelled by
-   * workspace, a second person's token in the same workspace would look like a
-   * reconnect of the first and overwrite their credential. `auth.test` returns
-   * both; `user` is the one that is unique per token.
+   * Not an override of discovery for its own sake — Slack publishes perfectly
+   * good metadata at `/.well-known/oauth-authorization-server` and these two
+   * values are copied from it. It is that the SDK ends its flow by posting to
+   * the token endpoint with the client *it* holds, and the client here is held
+   * by a broker. Declaring the endpoints is how a manifest says the exchange is
+   * ours to route. See `defineProvider` and ADR-040.
+   */
+  auth: {
+    kind: 'oauth',
+    registration: 'manual',
+    app: SLACK_APP,
+    authorize_url: 'https://slack.com/oauth/v2_user/authorize',
+    token_url: 'https://slack.com/api/oauth.v2.user.access',
+    scopes: [...SLACK_SCOPES],
+    broker: SLACK_BROKER,
+    /**
+     * Slack returns no refresh token, and that is the successful answer.
+     *
+     * A user token is long-lived unless token rotation is enabled on the app.
+     * Demanding one here would refuse every connection that worked — the
+     * default exists for Google, where a missing refresh token means the grant
+     * already existed and the connection would die in an hour.
+     */
+    refresh_token: 'optional',
+  },
+  /**
+   * The person *and* the workspace, because either alone collides.
+   *
+   * `settleIdentity` matches a resolved account against existing connections to
+   * decide whether this is a reconnect or a new account, so the string has to
+   * be unique per credential. Neither half of `auth.test` is:
+   *
+   *   - `team` alone — two people in one workspace look like one account, and
+   *     the second connect overwrites the first's token.
+   *   - `user` alone — Slack's "user" is a workspace-scoped handle, so one
+   *     person in two workspaces looks like a reconnect and the second
+   *     workspace overwrites the first. Connecting more than one workspace is
+   *     the ordinary case here, which made this the more likely of the two.
+   *
+   * Together they are unique, and `alice (Acme)` is a row somebody can read.
    *
    * Slack answers a bad token with HTTP 200 and `{ok: false}`, so a wrong token
    * reaches `connect`'s "which account is this?" fallback rather than a clear
    * refusal. Discovery fails loudly one step later, which is where the real
    * error is.
    */
-  identity: { kind: 'http', url: 'https://slack.com/api/auth.test', field: 'user' },
+  identity: {
+    kind: 'http',
+    url: 'https://slack.com/api/auth.test',
+    field: 'user',
+    qualifier: 'team',
+  },
   redact: SLACK_REDACT,
+  /**
+   * Read only by `--auth pasted_token`. The browser route asks for nothing.
+   *
+   * `connection` scope rather than `shared` is what makes `--own-client` refuse
+   * with "no bring-your-own client path", which is true: this asks for a token,
+   * never for a client of the operator's to register.
+   */
   setup: {
     summary:
-      'Slack needs an app of its own — there is no personal access token and no way to register ' +
-      'automatically, because Slack requires an HTTPS callback and this CLI listens on localhost. ' +
-      'You create the app once, install it to your workspace, and paste the user token it mints.',
+      'Slack normally needs nothing set up — one browser round trip against the app Lanes ' +
+      'registered. Pasting a token is the way past a workspace whose admin has not approved ' +
+      'that app, using one from an app the workspace already trusts.',
     docs: 'docs/detailed/setup/slack.md',
     docs_url: 'https://api.slack.com/apps',
     steps: [
-      'Open https://api.slack.com/apps and choose "Create New App" → "From scratch". Name it "Lanes Link" and pick the workspace.',
-      'Open "OAuth & Permissions" and scroll to "Scopes". Add these under USER TOKEN SCOPES — not Bot Token Scopes; the MCP server reads the user token: search:read.public, search:read.private, search:read.im, search:read.mpim, search:read.users, search:read.files, channels:history, groups:history, im:history, mpim:history, channels:read, groups:read, mpim:read, users:read, chat:write, files:read.',
-      'For reactions, canvases, or creating channels, add reactions:write, canvases:read, canvases:write, or channels:write as well. Those tools are listed either way and fail at call time without the scope.',
-      'Scroll up and choose "Install to Workspace", then approve. A Slack admin may have to approve it for you.',
-      'Copy the "User OAuth Token" from the same page. It starts with xoxp- — not the bot token, which starts with xoxb- and will not work here.',
-      'The token does not expire unless you enable token rotation on the app. If you rotate or reinstall, run: lanes link connect slack --replace.',
+      'Open https://api.slack.com/apps and choose "Create New App" → "From scratch". Name it and pick the workspace.',
+      'Open "OAuth & Permissions" and add the scopes you need under USER TOKEN SCOPES — not Bot Token Scopes; the MCP server reads the user token. The full set this provider asks for in the browser is listed in docs/detailed/setup/slack.md.',
+      'Choose "Install to Workspace" and approve. A Slack admin may have to approve it for you.',
+      'Copy the "User OAuth Token". It starts with xoxp- — not the bot token, which starts with xoxb- and will not work here.',
+      'The token does not expire unless you enable token rotation on the app. If you rotate or reinstall, run: lanes link connect slack --profile personal --target local --auth pasted_token --replace.',
     ],
     troubleshooting:
       'Slack refused the token. The usual causes are a bot token (xoxb-) pasted where the user token (xoxp-) belongs, ' +
       'a scope missing from USER TOKEN SCOPES, or an app that was reinstalled since — reinstalling mints a new token. ' +
-      'Copy the User OAuth Token from https://api.slack.com/apps and re-run: lanes link connect slack --replace.',
+      'Copy the User OAuth Token from https://api.slack.com/apps and re-run: lanes link connect slack --profile personal --target local --auth pasted_token --replace.',
     prompts: [
       {
         key: 'token',

package/src/providers/slack/oauth.ts

@@ -0,0 +1,103 @@
+import type { AuthBroker } from '#connectivity';
+import { brokerOriginOverride } from '#connectivity/auth/index.ts';
+
+/**
+ * Where Slack's client comes from, and why it cannot come from here.
+ *
+ * Slack refuses Dynamic Client Registration and says so in its documentation.
+ * That is not an omission waiting to be filled: DCR would let a client
+ * authenticate a user without an app existing, and on Enterprise Grid an admin
+ * approves each app before it can authenticate anyone. Waiting for it is
+ * waiting for something that is not coming.
+ *
+ * So somebody has to be pre-registered. Until now that somebody was the
+ * operator, once per person, in a browser tab, transcribing sixteen scopes. It
+ * is this project instead now — one app, registered once, exactly the
+ * arrangement every other client that connects to Slack without a console visit
+ * uses. See ADR-040.
+ */
+export const SLACK_APP = 'slack';
+
+const BROKER_ORIGIN = 'https://api.lanes.sh';
+const BROKER_PATH = '/v1/auth/link/slack';
+
+/**
+ * The client Lanes operates, reached at an origin an override can move.
+ *
+ * Same shape as Google's and for the same reasons — see
+ * `../google/shared/oauth.ts`. What differs is what a broker outage costs.
+ * Slack issues a long-lived user token and no refresh token unless token
+ * rotation is switched on for the app, so this is consulted at `connect` and
+ * never again: an outage here cannot interrupt an agent mid-request the way
+ * ADR-028 warned a shared dependency can. That is the whole of why the fallback
+ * below is a reasonable second answer rather than a necessary one.
+ */
+export function slackBroker(env?: Record<string, string | undefined>): AuthBroker {
+  return {
+    url: `${brokerOriginOverride(env) ?? BROKER_ORIGIN}${BROKER_PATH}`,
+    operator: 'Lanes',
+    docs_url: 'https://lanes.sh/link#slack',
+  };
+}
+
+export const SLACK_BROKER: AuthBroker = slackBroker();
+
+/**
+ * Where Slack sends the browser back — and why it is not this machine.
+ *
+ * Slack refuses to register a Redirect URL that is not HTTPS. Verified against
+ * a real app: the field rejects `http://localhost:<port>/callback` outright, so
+ * a loopback listener cannot be named to Slack at all. A CLI cannot be HTTPS
+ * either — there is no certificate for 127.0.0.1 a browser will accept.
+ *
+ * So the redirect goes to the broker, which bounces it straight down to the
+ * listener `connect` opened, carrying the port in `state`. The URL itself is
+ * not written here: `/config` publishes it, because which one is correct
+ * depends on which deployment answered, and a broker running on loopback for a
+ * test would otherwise need its own spelling of it.
+ *
+ * The cost is that Slack cannot be connected without the broker. Google's is
+ * optional — a profile may register its own client and never call it — and
+ * Slack's is not, because the broker *is* the HTTPS origin. Recorded in
+ * ADR-040, and softened by Slack issuing no refresh token: an outage stops
+ * `connect`, never a connection already made.
+ */
+
+/**
+ * What the browser grant asks for.
+ *
+ * These are user-token scopes: Slack's MCP server reads the user token, and a
+ * bot token is a different credential that does not work there at all. The list
+ * is what the setup page used to ask the operator to transcribe by hand, moved
+ * to where it can be shown before consent instead — which is what restores the
+ * scope-disclosure gate ADR-033 recorded as permanently absent for Slack.
+ *
+ * The last four are what `reactions`, `canvases`, and channel creation need.
+ * They are requested rather than left out because the tools appear in the list
+ * either way and fail at call time without them, and a tool that is visible and
+ * always fails is worse than a scope on the consent screen. What an agent may
+ * actually call is bounded by policy, where `connect` grants read and nothing
+ * else by default.
+ */
+export const SLACK_SCOPES = [
+  'search:read.public',
+  'search:read.private',
+  'search:read.im',
+  'search:read.mpim',
+  'search:read.users',
+  'search:read.files',
+  'channels:history',
+  'groups:history',
+  'im:history',
+  'mpim:history',
+  'channels:read',
+  'groups:read',
+  'mpim:read',
+  'users:read',
+  'chat:write',
+  'files:read',
+  'reactions:write',
+  'canvases:read',
+  'canvases:write',
+  'channels:write',
+] as const;