DottaandPaperclip
f0e12c8519
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Slack connects a person to an agent through an installed app and a verified identity. > - Independent installations must remain usable without Paperclip Cloud or manager credentials. > - Approved Cloud deployments can use Slack manager grants to create and install each agent's app. > - Both paths should share credential storage, identity checks, recovery, and the existing runtime. > - This pull request adds gated managed setup and keeps independent app setup under Advanced. > - It also makes ongoing connection settings and personal test messages easier to use. ## Linked Issues or Issue Description **Subsystem affected** Slack setup, connection settings, tenant credential storage, and the Cloud connector handoff. **Problem or motivation** Approved deployments need an installation flow without pasted configuration tokens. Open-source users must retain their independent Slack app flow. A connection manager also needs a simple way to check a bot from Settings. **Proposed solution** Use the managed path when the instance is configured to support it. Choose agent and Connect are the two visible stops. Continue starts authorization or installation. Use your own app remains under Advanced before creation. Save personal manager grants by company, Paperclip user, Slack user, workspace, and manager app. Reuse only verified identities for test messages. Unknown identities must complete a private Slack connection challenge before linking and receiving the test DM. **Alternatives considered** A shared bot would change each agent's Slack identity. Requiring Slack CLI or a hosted service for self-hosted users would remove independent installation. **Roadmap alignment** This maintainer-requested change improves Connected Apps and experimental Agent Chat. It adds provisioning and management controls to the existing Slack runtime. **Additional context** The companion Cloud broker profile is a separate deployment prerequisite. Managed setup remains gated. Existing-app adoption is deferred. ## What Changed - Extract Slack registration, provider requests, completion, customer-owned setup, managed setup, and personal manager grants into focused services. Preserve the compatibility facade and independent removal cleanup. - Add company-scoped manager grants and a registration reference through an additive, idempotent migration after current master. Keep runtime credentials separate from app-registration secrets. - Add authenticated manager authorization, sealed handoff, serialized refresh and revocation, app creation, managed installation, and installer-bound OAuth fallback. - Preserve creation intent, block automatic uncertain recreation, save credentials before downstream checks, and validate app, workspace, bot, scopes, and installer identity. - Add the two-stop production wizard and ordered stories. Keep the own-app, manual, existing-app, and legacy-draft paths. - Simplify Settings. Open Slack configuration targets the saved app. The test-message action has its own row. Remove the old manual-avatar section, channel-message section, and broken permissions link. - Add paginated account discovery and a private connection challenge for unknown accounts. Expired invitations stop waiting and offer a new private invitation. Save send receipts before provider dispatch and preserve confirmed delivery when activity logging fails. - Reinstall the saved managed app on explicit reconnect, replace revoked credentials, and resume completion. Persist reconnect intent and duplicate-request receipts without creating another app. - Update provider browser tests, recovery tests, secret redaction, setup documentation, and the agent prompt. Preserve current master's durable verification scheduling. ## Verification - Full workspace typecheck and repository build passed on `56d389d47a`. The subsequent reconnect retry fix in `288364eada` also passed UI typecheck and UI build. - 114 focused Slack registration cases and 13 production managed-wizard cases passed, including fresh-token reconnect, retry after installation failure, and duplicate reconnect requests. - All nine affected Slack browser cases passed against the production UI and a disposable fixture server. They cover managed setup, automatic setup, own-app selection, refresh, recovery, mobile behavior, and connection settings. - Eight focused real-database test-message cases passed. They cover a private ownership challenge, saved grant reuse, account pagination, revoked and conflicting links, workspace mismatch, disabled DMs, revoked membership, audit failure, ambiguous dispatch, and secret canaries. - UI token gates and the production Storybook build passed. - Greptile reviewed exact head `288364eada5d9c114fad991ff634612639d06672` at 5/5 with no actionable findings or unresolved review threads. - The full repository test suite and current-head CI are running. Their final results will replace this line before merge. - Earlier live feature previews created two bots in the authorized Paperclip Slack workspace and reused one personal manager grant. Local managed Continue created and installed a bot without a configuration token or a separate Add to Slack action. Avatars, welcome DMs, signed callbacks, and direct replies were observed. A Settings test DM also arrived in the signed-in user's Slack account. - Earlier staging thread qualification required manual publication recovery for one bot. Current-head live qualification remains required before enabling the production default. Fixture results do not establish Slack approval behavior in other workspaces. ## Risks - Personal manager tokens can create apps. They stay in scoped vault entries. The manager client secret stays at the broker. Company, actor/session, origin, and app identity checks apply throughout setup. - The additive migration must also work on qualification instances that applied earlier branch migrations. Table, column, index, and constraint creation is idempotent. - Creation and message timeouts can leave uncertain outcomes. Saved request IDs prevent automatic duplicate dispatch. - Unknown Slack identities must receive and complete their private challenge while signed in. Account selection alone does not grant Paperclip permissions. Existing revoked or conflicting links are not overwritten. - A development-only manager transport uses an explicitly configured private credential file for local qualification. Production ignores this transport; no manager credentials are bundled with open source. - Managed rollout requires Slack approval, the companion broker deployment, configured secrets, and final live qualification. Removing a connection does not delete its Slack app. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, code execution, and browser tools. The session does not expose the exact serving model ID or context-window size. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [ ] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
10 KiB
Slack app ownership and setup
Slack has one chat runtime and two provisioning paths. A saved connection's
slackSetupMethod selects provisioning; it does not change tools, scopes,
conversation routing, people permissions, or channel access.
| Method | App creation and installation | Default |
|---|---|---|
managed |
A personal Slack manager grant creates a child app; managed installation supplies its bot token. Slack consent/admin approval remains a fallback. | New drafts on qualified Cloud deployments only |
automatic |
A temporary app configuration access token creates a customer-owned app; the user approves its OAuth installation. | New self-hosted drafts and Cloud without managed availability |
manual |
User creates an app from the canonical manifest and enters credentials. | Legacy drafts with no saved method |
existing |
User supplies credentials for an existing app. | Explicit selection |
Existing drafts and active bots retain their method. Enabling managed setup never adopts existing apps. Choose agent offers Use your own app under Advanced, below Slash command, when the instance supports managed setup and creation has not started. The own-app flow retains Create manually and Use an existing app under Advanced. After creation dispatch, a managed draft cannot switch paths.
Managed setup has two visible stops: Choose agent and Connect. Continue starts manager authorization or installation in the saved workspace automatically. Multiple workspaces still require a selection. Recovery actions remain explicit; opening a failed or uncertain registration never retries creation automatically. Creation, installation, message waiting, and success use the same production components and server evidence as the own-app flow. A click or OAuth return does not constitute successful configuration.
Cloud deployment prerequisites
Managed setup is disabled by default. Qualification requires all of:
- The instance chat-connector rollout gate and connection-management permission.
- Verified Cloud runtime identity, connector broker signing/sealing configuration, and valid independently configured public board and webhook HTTPS origins.
PAPERCLIP_SLACK_MANAGED_SETUP_ENABLED=trueon the approved tenant deployment.- The companion Cloud broker deployment with the explicitly enabled
slack.managerprofile, approved Slack manager app, token rotation, and its client secret in the broker's secret store. No manager client secret belongs in the tenant.
The broker must advertise its manager app identity as well as the enabled profile. Previously saved grants from a different manager app are not reused. A broker without this capability leaves managed setup unavailable. Do not enable the tenant gate until real Slack qualification has passed; fixture coverage does not prove Marketplace eligibility or a workspace's approval policy.
Self-hosted instances do not need a Paperclip account, broker enrollment, manager credentials, or hosted-service calls. They continue using the own-app flow.
Personal workspace authorization
Manager grants belong to a company and one Paperclip user, and bind a verified Slack user, workspace, and manager app. Another company member must authorize their own account, even for the same workspace. Access and rotating refresh tokens are user-scoped vault entries. Refreshes serialize across connections, persist the new refresh token, and require fresh authorization after an ambiguous exchange.
Revoking a grant requests provider revocation, removes its local credentials, invalidates pending manager authorization, and prevents future provisioning with it. The local activity records whether provider revocation succeeded. Provider errors never restore local access. It does not uninstall apps or disable already-installed bots. Removing a bot deletes endpoint-specific secrets and pending setup attempts; a reusable personal manager grant survives. Provider-side app removal remains explicit through the saved Slack management URL.
Recovery
- A dispatched creation with an unknown result is uncertain. Never automatically create again. The user must inspect Slack and explicitly confirm that no app was created before a new request identity is accepted.
- Denied or pending installation retains the app. Resume with the same grant or complete the child app's state-bound OAuth approval; the installer must match the grant's Slack identity before personal linking.
- Returned bot credentials are vaulted before inventory or runtime configuration. Retry connecting reuses those credentials after network or inventory failures. Rejected or under-scoped bot credentials instead reinstall the saved app; they never trigger another app creation.
- Manifest updates finish before managed installation. Changes requiring updated permissions therefore pass through installation again before activation.
- Expired or revoked manager grants require reconnection. Losing managed availability pauses setup; it never changes the saved ownership method.
- Slack rate limits are grouped by manager/workspace/method. Provider
Retry-Afteris persisted across matching grants in the company, survives restarts, and blocks early retries. Other tenant instances must observe Slack's limits independently; no background loop retries app creation.
All OAuth attempts bind company, actor/session, endpoint, registration revision, and configured origins, expire after ten minutes, and are claimed once before exchange. HTTP diagnostics redact manager tokens, refresh tokens, codes, and sealed handoffs. Local activity records contain only IDs and safe outcome codes. This adds no first-party telemetry.
Code and verification
Server provisioning lives in server/src/services/connectors/slack/setup/;
chat-slack-registration.ts remains the compatibility facade. Shared completion
owns credential binding, personal linking, welcome messages, and verification.
Removal cleanup stays independently callable. Slack wizard components and stage
selection live in ui/src/pages/apps/chat/slack/.
Production Storybook journeys: Connections / Slack / Managed setup and
Connections / Slack / Automatic setup (the persisted own-app automatic path).
Server integration cases cover personal grants, duplicate requests, uncertain
creation, approval fallback, refresh, revocation, removal, saved-credential recovery,
rate limits, and secret canaries. Browser cases are in
tests/e2e/chat-adapters-ui-providers.spec.ts; companion broker tests cover manager
user OAuth and the authenticated tenant handoff.
Before enabling a deployment, create two test agents in the authorized workspace. The second must reuse the personal grant without another configuration token or manager authorization. Verify avatars, identity linking, signed inbound events, and same-thread replies. Record real approval behavior separately from fixtures.
Managed setup during broker outages
Cloud deployments configured for managed Slack keep the managed default when the broker profile is temporarily unavailable. New drafts remain on Connect and offer Retry. Use your own app remains available under Advanced on Choose agent before creation. Discovery loading or failure never selects the configuration-token page. Self-hosted instances without managed configuration still use their independent own-app flow; saved draft methods do not change automatically. Provisioning continues to require current broker availability.
Local managed-bot qualification
Maintainers with an approved Slack manager app can exercise the real managed journey from an authenticated local test drive exposed through HTTPS (including TryCloudflare). This development transport talks directly to Slack and reuses the production manager-grant vault, state claims, provisioning, completion, and runtime. It does not exercise the Cloud broker's sealed handoff; qualify that separately on staging afterward.
Set NODE_ENV=development, PAPERCLIP_SLACK_MANAGED_SETUP_ENABLED=true, and
PAPERCLIP_SLACK_MANAGER_DEVELOPMENT_CONFIG to an absolute path outside the
checkout containing a mode-0600 JSON file with appId, clientId, and
clientSecret. Use only an authorized qualification manager app. No credentials
are shipped with Paperclip. Production ignores this development configuration,
and Cloud runtime identity continues to select the Cloud broker.
Configure the local instance for authenticated public access, with its public
URL and chat webhook URL pointing to the HTTPS tunnel. Add the exact public URL
plus /api/chat-slack/managed/oauth/callback to the manager app's OAuth redirect
URLs, preserving any existing redirects. Start a new Slack setup: saved
own-app drafts retain their selected method. Authorize the manager app normally;
do not copy user grants from another instance. The second bot should reuse the
same local user's vaulted grant. A changed tunnel requires updating public
origins and the manager redirect before starting fresh authorization.
Remove the temporary redirect when retiring the test drive and securely remove its development credential file. Removing a bot does not revoke a manager grant used by other bots.
Test messages from Settings
Send me a test message sends a DM to the signed-in connection manager, using their linked identity in this workspace. If this bot is not linked yet, Paperclip can reuse that user's verified manager grant or another bot's linked identity in the same company and workspace. Otherwise, the user selects their Slack account and receives a private connection invitation in Slack. They must open that invitation, sign in, and confirm before Paperclip links the account and sends the test DM. The account picker loads further workspace pages on request. Existing revoked or conflicting identity links are not overwritten. Direct messages must be enabled, and the user must be an active company operator.
The action records a durable request before sending. Repeating the same request returns its saved result; an uncertain delivery is never automatically resent. Open Slack configuration opens the saved app's OAuth & Permissions page. Legacy connections without an app ID open Slack's app list instead.
An explicit managed reconnect reinstalls the saved app and verifies the replacement bot credentials. Its request ID is saved before dispatch, so a duplicate completed request does not reinstall again. Credential-configuration recovery still resumes the saved token after a downstream failure. No reconnect creates another Slack app.