@lanes-sh/link 0.2.2 → 0.3.1

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;

package/src/providers/slack/scopes.ts

@@ -0,0 +1,37 @@
+import type { ScopeMeaning } from '../scopes.ts';
+
+/**
+ * Slack's user-token scopes, said in words before the browser opens.
+ *
+ * These used to be sixteen lines of a setup page the operator transcribed into
+ * a console, where nothing described them and nothing could refuse. Asking for
+ * them in a browser is what makes `confirmScopes` apply to Slack at all — the
+ * gate ADR-033 recorded as permanently absent here.
+ *
+ * `broad` is set for the four that reach private conversations and the one that
+ * writes as the person. A grant of `search:read.private` is not "search" in the
+ * sense a reader assumes: it covers every private channel and DM the account
+ * can see, which is usually the most sensitive thing in the workspace.
+ */
+export const SLACK_SCOPE_MEANINGS: Record<string, ScopeMeaning> = {
+  'search:read.public': { meaning: 'search public channels' },
+  'search:read.private': { meaning: 'search private channels', broad: true },
+  'search:read.im': { meaning: 'search direct messages', broad: true },
+  'search:read.mpim': { meaning: 'search group direct messages', broad: true },
+  'search:read.users': { meaning: 'search people in the workspace' },
+  'search:read.files': { meaning: 'search files' },
+  'channels:history': { meaning: 'read messages in public channels' },
+  'groups:history': { meaning: 'read messages in private channels', broad: true },
+  'im:history': { meaning: 'read direct messages', broad: true },
+  'mpim:history': { meaning: 'read group direct messages', broad: true },
+  'channels:read': { meaning: 'list public channels' },
+  'groups:read': { meaning: 'list private channels' },
+  'mpim:read': { meaning: 'list group direct messages' },
+  'users:read': { meaning: 'read people and profiles' },
+  'chat:write': { meaning: 'send messages as you', broad: true },
+  'files:read': { meaning: 'read files and their contents' },
+  'reactions:write': { meaning: 'add and remove reactions as you' },
+  'canvases:read': { meaning: 'read canvases' },
+  'canvases:write': { meaning: 'create and edit canvases' },
+  'channels:write': { meaning: 'create and manage public channels' },
+};

package/src/server/container.ts

@@ -24,7 +24,9 @@ import { streamLogger } from './logging.ts';
  *                      nobody wrote — so the endpoint refuses rather than
  *                      serving an empty workspace.
  *   LANES_LINK_TARGET   which target's adapters to open. Baked to `cloud`.
- *   LANES_LINK_PROFILE  optional; the workspace default otherwise.
+ *   LANES_LINK_PROFILE  the primary profile this revision serves. Required —
+ *                      there is no workspace default any more (ADR-037), and
+ *                      `lanes link deploy` sets it at rollout.
  *   PORT               injected by Cloud Run. 8080 is its default.
  */
 
@@ -42,6 +44,21 @@ if (!Number.isInteger(port) || port < 1 || port > 65535) {
 }
 const host = env['LANES_LINK_HOST'] ?? '0.0.0.0';
 
+// In this container's own voice, not the CLI's. A revision serves one primary
+// profile — it decides the token that opens the endpoint — and nothing here can
+// pick one. `lanes link deploy` sets the variable at rollout, in the same
+// `gcloud run deploy` as the image, so the two never disagree; a container
+// started by hand has to be told. Refusing here beats a CLI-shaped "pass
+// --profile" reaching a log where there is no command line to pass it on.
+if (!env['LANES_LINK_PROFILE']) {
+  process.stderr.write(
+    'LANES_LINK_PROFILE is not set on this service. A deployed revision serves one\n' +
+      'primary profile and must be told which. `lanes link deploy` sets it at rollout;\n' +
+      'if this container was started by hand, pass -e LANES_LINK_PROFILE=<name>.\n',
+  );
+  process.exit(1);
+}
+
 const log = (message: string): void => {
   process.stdout.write(`${new Date().toISOString()} ${message}\n`);
 };