Add a user-token OAuth method to the Slack app #2368

--- a/README.md
+++ b/README.md
@@ -8,12 +8,27 @@
 
 **Auth**
 
-- Token: a bot token (`xoxb-`) or user token (`xoxp-`) from your Slack app's "OAuth & Permissions" page at https://api.slack.com/apps. User tokens are needed for methods such as `search.messages`.
-- OAuth: create a Slack app at https://api.slack.com/apps, add the redirect URI shown on Executor's connect page under "OAuth & Permissions", and enter its client ID and secret. The flow requests bot scopes (comma separated) and yields a bot token; reduce the scopes to what the app needs. Every requested scope was checked against its docs.slack.dev scope page as a bot scope; `mpim:write` is user-token only and is not requested.
+- Token: a bot token (`xoxb-`) or user token (`xoxp-`) from your Slack app's "OAuth & Permissions" page at https://api.slack.com/apps. This method keeps the supplied token as-is.
+- User OAuth (`user`): create a Slack app at https://api.slack.com/apps, add the redirect URI shown on the host's connect page, add the scopes below under **User Token Scopes**, and enter the client ID and secret. This flow sends a comma-separated `user_scope` only; it omits the OAuth `scope` parameter and does not request a bot grant. The exchange requires `authed_user.access_token`, which is used for health checks and API calls.
 
+  `user_scope` contains:
+
+  - Conversations: `channels:history`, `channels:read`, `channels:write`, `groups:history`, `groups:read`, `groups:write`, `im:history`, `im:read`, `im:write`, `mpim:history`, `mpim:read`, `mpim:write`.
+  - Messages and search: `chat:write`, `links:write`, `reactions:read`, `reactions:write`, `search:read`.
+  - Files: `files:read`, `files:write`, `remote_files:read`, `remote_files:share`.
+  - Calls and presence: `calls:read`, `calls:write`, `dnd:read`, `dnd:write`, `users:write`.
+  - Pins, reminders and workspace data: `emoji:read`, `pins:read`, `pins:write`, `reminders:read`, `reminders:write`, `team:read`, `usergroups:read`, `usergroups:write`, `users.profile:read`, `users.profile:write`, `users:read`, `users:read.email`.
+
+- Bot OAuth (`oauth`): use the existing bot-token flow with the redirect URI shown on the host's connect page, then enter the Slack app's client ID and secret. It requests the existing bot scopes and continues to use the top-level bot access token.
+
 **Known gaps**
 
 - No operations are skipped after the patches (171 of the 174 spec operations are exposed; the 3 removed are the oauth.* methods above).
-- OAuth yields a bot token only; user-token-only methods (search, some admin methods) need the token method.
+- The OpenAPI router exposes 171 methods. Admin methods still need admin scopes, and methods whose Slack documentation requires a bot or app-level token cannot use this user grant.
+- [`files.remote.add`](https://docs.slack.dev/reference/methods/files.remote.add/), [`files.remote.remove`](https://docs.slack.dev/reference/methods/files.remote.remove/), and [`files.remote.update`](https://docs.slack.dev/reference/methods/files.remote.update/) require `remote_files:write`. Slack documents that scope as bot-token-only and says remote files must be added by bots, not individual users. The user grant includes `remote_files:read` and `remote_files:share`, but not these writes.
+- Slack's [`stars.add`](https://docs.slack.dev/reference/methods/stars.add/), [`stars.list`](https://docs.slack.dev/reference/methods/stars.list/), and [`stars.remove`](https://docs.slack.dev/reference/methods/stars.remove/) methods still accept user scopes, but current docs say users can no longer view or interact with saved items through these APIs and recommend retiring app functionality that relies on them. The user grant does not request `stars:read` or `stars:write`.
+- Slack rejects `tokens.basic` as an illegal user scope during app registration. The user grant omits it.
+- [`users.identity`](https://docs.slack.dev/reference/methods/users.identity/) requires Slack identity scopes, which this grant intentionally omits.
+- The user grant omits `bookmarks:*` and `canvases:*` because the maintained OpenAPI description contains no corresponding operations.
 - File uploads via the legacy multipart `files.upload` are not supported.
 - Icon is Slack's hash mark from the Slack website (`a.slack-edge.com`), as Simple Icons has no Slack entry.
--- a/index.ts
+++ b/index.ts
@@ -11,11 +11,52 @@
   string,
   withApprovals,
 } from "apps";
-import { always } from "apps/operations/approval";
+import { always, never } from "apps/operations/approval";
 import { liveOpenapiRouter } from "apps/openapi";
 import { icons } from "./icon.js";
 import { options } from "./openapi.js";
 
+const userScopes = [
+  "calls:read",
+  "calls:write",
+  "channels:history",
+  "channels:read",
+  "channels:write",
+  "chat:write",
+  "dnd:read",
+  "dnd:write",
+  "emoji:read",
+  "files:read",
+  "files:write",
+  "groups:history",
+  "groups:read",
+  "groups:write",
+  "im:history",
+  "im:read",
+  "im:write",
+  "links:write",
+  "mpim:history",
+  "mpim:read",
+  "mpim:write",
+  "pins:read",
+  "pins:write",
+  "reactions:read",
+  "reactions:write",
+  "reminders:read",
+  "reminders:write",
+  "remote_files:read",
+  "remote_files:share",
+  "search:read",
+  "team:read",
+  "usergroups:read",
+  "usergroups:write",
+  "users.profile:read",
+  "users.profile:write",
+  "users:read",
+  "users:read.email",
+  "users:write",
+] as const;
+
 // Slack answers HTTP 200 with {ok:false,error} for bad tokens, so decode `ok` first and only
 // then rely on the fields that are present on success.
 const Auth = object({
@@ -30,6 +71,16 @@
   name: "Slack",
   hosts: ["slack.com"],
   auth: {
+    // Request only user scopes and require Slack's nested user grant on exchange.
+    user: oauth2({
+      authorizationUrl: "https://slack.com/oauth/v2/authorize",
+      tokenUrl: "https://slack.com/api/oauth.v2.access",
+      tokenEndpointAuthMethod: "client_secret_post",
+      scopeSeparator: ",",
+      scopes: [],
+      authorizationParams: { user_scope: userScopes.join(",") },
+      tokenResponse: { path: "authed_user", requiredOnExchange: true },
+    }),
     token: secrets({
       label: "Bot or user token (xoxb-/xoxp-)",
       fields: object({ token: string({ minLength: 1 }) }),
@@ -75,7 +126,10 @@
     }),
   },
   async health({ account, fetch, signal }) {
-    const token = account.method === "oauth" ? account.fields.access_token : account.fields.token;
+    const token =
+      account.method === "user" || account.method === "oauth"
+        ? account.fields.access_token
+        : account.fields.token;
     const response = await fetch("https://slack.com/api/auth.test", {
       method: "POST",
       signal,
@@ -97,7 +151,7 @@
         user?.accounts.slack ?? [],
         (account) =>
           withApprovals(liveOpenapiRouter({ ...options, cache, fetch, signal, account }), (tool) =>
-            tool.kind === "mutation" ? always() : undefined,
+            tool.kind === "mutation" ? always() : never(),
           ),
         { signal },
       ),
--- a/openapi.ts
+++ b/openapi.ts
@@ -40,6 +40,7 @@
   allowedOrigin: "https://slack.com",
   securitySchemes: { slackAuth: { type: "http", scheme: "bearer" } },
   methods: {
+    user: [{ scheme: "slackAuth", field: "access_token", part: "value", prefix: "" }],
     token: [{ scheme: "slackAuth", field: "token", part: "value", prefix: "" }],
     oauth: [{ scheme: "slackAuth", field: "access_token", part: "value", prefix: "" }],
   },