or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

error-handling.mdindex.mdinstallation-storage.mdoauth-flow.mdstate-management.md
tile.json

tessl/npm-slack--oauth

Official library for interacting with Slack's OAuth endpoints

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@slack/oauth@3.0.x

To install, run

npx @tessl/cli install tessl/npm-slack--oauth@3.0.0

index.mddocs/

Slack OAuth

Slack OAuth is the official TypeScript/JavaScript library for handling Slack app OAuth installations. It provides a complete OAuth 2.0 implementation with support for both modern Slack Apps (v2) and Classic Slack apps (v1), state management for CSRF protection, and flexible storage solutions for installation data.

Package Information

  • Package Name: @slack/oauth
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @slack/oauth

Core Imports

import { InstallProvider } from "@slack/oauth";

For CommonJS:

const { InstallProvider } = require("@slack/oauth");

Basic Usage

import { InstallProvider } from "@slack/oauth";

// Initialize the OAuth provider
const installer = new InstallProvider({
  clientId: process.env.SLACK_CLIENT_ID,
  clientSecret: process.env.SLACK_CLIENT_SECRET,
  stateSecret: "my-state-secret",
});

// Handle install path
app.get("/slack/install", async (req, res) => {
  await installer.handleInstallPath(req, res, undefined, {
    scopes: ["chat:write", "commands"],
  });
});

// Handle OAuth callback
app.get("/slack/oauth_redirect", async (req, res) => {
  await installer.handleCallback(req, res);
});

// Authorize requests
const authResult = await installer.authorize({
  teamId: "T1234567890",
  isEnterpriseInstall: false,
});

Architecture

Slack OAuth is built around several core components:

  • InstallProvider: Main OAuth coordinator handling the complete OAuth flow
  • Installation Storage: Pluggable storage interfaces for persisting app installation data
  • State Management: CSRF protection through encrypted state parameters
  • OAuth Versions: Support for both OAuth v1 (Classic Apps) and v2 (Granular Bot Permissions)
  • Error Handling: Comprehensive error types for OAuth-specific failures

Capabilities

OAuth Flow Management

Complete OAuth 2.0 flow implementation with install URL generation, callback handling, and token exchange. Handles both bot and user token installation patterns.

class InstallProvider {
  constructor(options: InstallProviderOptions);
  async handleInstallPath(
    req: IncomingMessage, 
    res: ServerResponse, 
    installOptions?: InstallURLOptions
  ): Promise<void>;
  async generateInstallUrl(options: InstallURLOptions): Promise<string>;
  async handleCallback(
    req: IncomingMessage, 
    res: ServerResponse, 
    options?: CallbackOptions
  ): Promise<void>;
  async authorize(source: InstallationQuery<boolean>): Promise<AuthorizeResult>;
}

interface InstallProviderOptions {
  clientId: string;
  clientSecret: string;
  stateSecret?: string;
  installationStore?: InstallationStore;
  stateStore?: StateStore;
  authVersion?: "v1" | "v2";
  // ... additional options
}

OAuth Flow Management

Installation Storage

Flexible storage system for persisting and retrieving app installation data including tokens, team information, and user details.

interface InstallationStore {
  storeInstallation<AuthVersion extends "v1" | "v2">(
    installation: Installation<AuthVersion, boolean>,
    logger?: Logger
  ): Promise<void>;
  fetchInstallation(
    query: InstallationQuery<boolean>,
    logger?: Logger
  ): Promise<Installation<"v1" | "v2", boolean>>;
  deleteInstallation?(
    query: InstallationQuery<boolean>,
    logger?: Logger
  ): Promise<void>;
}

interface Installation<AuthVersion extends "v1" | "v2", IsEnterpriseInstall extends boolean> {
  team: IsEnterpriseInstall extends true ? undefined : { id: string; name?: string };
  enterprise?: { id: string; name?: string };
  bot?: { token: string; scopes: string[]; id: string; userId: string };
  user?: { token: string; scopes: string[]; id: string };
  // ... additional properties
}

Installation Storage

State Management

CSRF protection through encrypted state parameters that securely transfer installation options between OAuth endpoints.

interface StateStore {
  generateStateParam(
    installOptions: InstallURLOptions,
    now: Date
  ): Promise<string>;
  verifyStateParam(now: Date, state: string): Promise<InstallURLOptions>;
}

interface StateObj {
  now: Date;
  installOptions: InstallURLOptions;
  random?: string | number;
}

State Management

Error Handling

Comprehensive error types with specific codes for different OAuth failure scenarios.

enum ErrorCode {
  InstallerInitializationError = "slack_oauth_installer_initialization_error";
  AuthorizationError = "slack_oauth_installer_authorization_error";
  GenerateInstallUrlError = "slack_oauth_generate_url_error";
  MissingStateError = "slack_oauth_missing_state";
  InvalidStateError = "slack_oauth_invalid_state";
  MissingCodeError = "slack_oauth_missing_code";
  UnknownError = "slack_oauth_unknown_error";
}

interface CodedError extends Error {
  code: string;
}

Error Handling