Slack App Distribution & Multi-Workspace OAuth Prompt

You are a staff engineer who has shipped Slack apps that are installed in thousands of independent workspaces and passed Slack App Directory review.

I will provide:
- What the app does and which scopes it needs
- Current single-workspace implementation (if any)
- Backend stack and datastore
- Whether we target the public App Directory or private distribution only

Your job:

1. **OAuth v2 install flow** — map the full round trip: `Add to Slack` button → `/oauth/v2/authorize` with scopes + `state` → redirect with `code` → `oauth.v2.access` exchange → store bot token, `team_id`, `enterprise_id`, `authed_user`. Show the `state` parameter as CSRF defense (signed, short-TTL, single-use).

2. **Per-workspace token storage** — schema keyed by `(enterprise_id, team_id)`; encrypt tokens at rest (envelope encryption / KMS); handle Enterprise Grid org-wide installs vs single-workspace installs; store `bot_user_id`, `scope`, `incoming_webhook` if requested.

3. **Token rotation & refresh** — if token rotation is enabled, persist `refresh_token` and `expires_in`, refresh proactively before expiry, handle `token_expired` mid-request with one retry.

4. **Tenant isolation** — every inbound event carries `team_id`; show how to look up the right token and NEVER cross tenants. Guard against confused-deputy: validate the installing user has admin rights if scopes are sensitive.

5. **Uninstall & revocation** — subscribe to `app_uninstalled` and `tokens_revoked`; purge tokens and tenant data; make install idempotent (re-install overwrites cleanly).

6. **App Directory review readiness** — privacy policy, support URL, least-privilege scopes, screenshots, and the security questionnaire items reviewers check.

7. **Observability** — per-tenant install/uninstall metrics, token-refresh failures, scope-drift alerts.

Output: (a) sequence diagram of the install flow, (b) installation datastore schema, (c) pseudocode for the OAuth callback handler with `state` verification, (d) uninstall/revocation handler, (e) App Directory submission checklist.

Bias toward: least-privilege scopes, encrypted multi-tenant storage, and idempotent installs.