Fix #982 Enable developers to customize the "/slack/install" webpage content

src/receivers/ExpressReceiver.ts

@@ -11,7 +11,7 @@ import { InstallProvider, CallbackOptions, InstallProviderOptions, InstallURLOpt
 import App from '../App';
 import { ReceiverAuthenticityError, ReceiverMultipleAckError, ReceiverInconsistentStateError } from '../errors';
 import { AnyMiddlewareArgs, Receiver, ReceiverEvent } from '../types';
-import renderHtmlForInstallPath from './render-html-for-install-path';
+import defaultRenderHtmlForInstallPath from './render-html-for-install-path';
 
 // Option keys for tls.createServer() and tls.createSecureContext(), exclusive of those for http.createServer()
 const httpsOptionKeys = [
@@ -94,6 +94,7 @@ interface InstallerOptions {
  metadata?: InstallURLOptions['metadata'];
  installPath?: string;
  directInstall?: boolean; // see https://api.slack.com/start/distributing/directory#direct_install
+ renderHtmlForInstallPath?: (url: string) => string;
  redirectUriPath?: string;
  callbackOptions?: CallbackOptions;
  userScopes?: InstallURLOptions['userScopes'];
@@ -202,7 +203,10 @@ export default class ExpressReceiver implements Receiver {
  res.redirect(url);
  } else {
  // The installation starts from a landing page served by this app.
- res.send(renderHtmlForInstallPath(url));
+ const renderHtml = installerOptions.renderHtmlForInstallPath !== undefined ?
+ installerOptions.renderHtmlForInstallPath :
+ defaultRenderHtmlForInstallPath;
+ res.send(renderHtml(url));
  }
  } catch (error) {
  next(error);

src/receivers/HTTPReceiver.spec.ts

@@ -160,7 +160,51 @@ describe('HTTPReceiver', function () {
  assert(installProviderStub.generateInstallUrl.calledWith(sinon.match({ metadata, scopes, userScopes })));
  assert.isTrue(writeHead.calledWith(200));
  });
- it('should redirect installers if directInstallEnabled is true', async function () {
+ it('should use a custom HTML renderer for the install path webpage', async function () {
+ // Arrange
+ const installProviderStub = sinon.createStubInstance(InstallProvider);
+ const overrides = mergeOverrides(
+ withHttpCreateServer(this.fakeCreateServer),
+ withHttpsCreateServer(sinon.fake.throws('Should not be used.')),
+ );
+ const HTTPReceiver = await importHTTPReceiver(overrides);
+
+ const metadata = 'this is bat country';
+ const scopes = ['channels:read'];
+ const userScopes = ['chat:write'];
+ const receiver = new HTTPReceiver({
+ logger: noopLogger,
+ clientId: 'my-clientId',
+ clientSecret: 'my-client-secret',
+ signingSecret: 'secret',
+ stateSecret: 'state-secret',
+ scopes,
+ installerOptions: {
+ authVersion: 'v2',
+ installPath: '/hiya',
+ renderHtmlForInstallPath: (_) => 'Hello world!',
+ metadata,
+ userScopes,
+ },
+ });
+ assert.isNotNull(receiver);
+ receiver.installer = installProviderStub as unknown as InstallProvider;
+ const fakeReq: IncomingMessage = sinon.createStubInstance(IncomingMessage) as IncomingMessage;
+ fakeReq.url = '/hiya';
+ fakeReq.headers = { host: 'localhost' };
+ fakeReq.method = 'GET';
+ const fakeRes: ServerResponse = sinon.createStubInstance(ServerResponse) as unknown as ServerResponse;
+ const writeHead = sinon.fake();
+ const end = sinon.fake();
+ fakeRes.writeHead = writeHead;
+ fakeRes.end = end;
+ /* eslint-disable-next-line @typescript-eslint/await-thenable */
+ await receiver.requestListener(fakeReq, fakeRes);
+ assert(installProviderStub.generateInstallUrl.calledWith(sinon.match({ metadata, scopes, userScopes })));
+ assert.isTrue(writeHead.calledWith(200));
+ assert.isTrue(end.calledWith('Hello world!'));
+ });
+ it('should rediect installers if directInstall is true', async function () {
  // Arrange
  const installProviderStub = sinon.createStubInstance(InstallProvider);
  const overrides = mergeOverrides(

src/receivers/HTTPReceiver.ts

@@ -9,7 +9,7 @@ import { URL } from 'url';
 import { verify as verifySlackAuthenticity, BufferedIncomingMessage } from './verify-request';
 import App from '../App';
 import { Receiver, ReceiverEvent } from '../types';
-import renderHtmlForInstallPath from './render-html-for-install-path';
+import defaultRenderHtmlForInstallPath from './render-html-for-install-path';
 import {
  ReceiverMultipleAckError,
  ReceiverInconsistentStateError,
@@ -70,6 +70,7 @@ export interface HTTPReceiverOptions {
 export interface HTTPReceiverInstallerOptions {
  installPath?: string;
  directInstall?: boolean; // see https://api.slack.com/start/distributing/directory#direct_install
+ renderHtmlForInstallPath?: (url: string) => string;
  redirectUriPath?: string;
  stateStore?: InstallProviderOptions['stateStore']; // default ClearStateStore
  authVersion?: InstallProviderOptions['authVersion']; // default 'v2'
@@ -102,6 +103,8 @@ export default class HTTPReceiver implements Receiver {
 
  private directInstall?: boolean; // always defined when installer is defined
 
+ private renderHtmlForInstallPath: (url: string) => string;
+
  private installRedirectUriPath?: string; // always defined when installer is defined
 
  private installUrlOptions?: InstallURLOptions; // always defined when installer is defined
@@ -164,6 +167,9 @@ export default class HTTPReceiver implements Receiver {
  };
  this.installCallbackOptions = installerOptions.callbackOptions ?? {};
  }
+ this.renderHtmlForInstallPath = installerOptions.renderHtmlForInstallPath !== undefined ?
+ installerOptions.renderHtmlForInstallPath :
+ defaultRenderHtmlForInstallPath;
 
  // Assign the requestListener property by binding the unboundRequestListener to this instance
  this.requestListener = this.unboundRequestListener.bind(this);
@@ -438,7 +444,7 @@ export default class HTTPReceiver implements Receiver {
  } else {
  // The installation starts from a landing page served by this app.
  // Generate HTML response body
- const body = renderHtmlForInstallPath(url);
+ const body = this.renderHtmlForInstallPath(url);
 
  // Serve a basic HTML page including the "Add to Slack" button.
  // Regarding headers:

src/receivers/SocketModeReceiver.spec.ts

@@ -201,6 +201,49 @@ describe('SocketModeReceiver', function () {
  assert(fakeRes.writeHead.calledWith(200, sinon.match.object));
  assert(fakeRes.end.called);
  });
+ it('should use a custom HTML renderer for the install path webpage', async function () {
+ // Arrange
+ const installProviderStub = sinon.createStubInstance(InstallProvider);
+ const overrides = mergeOverrides(
+ withHttpCreateServer(this.fakeCreateServer),
+ withHttpsCreateServer(sinon.fake.throws('Should not be used.')),
+ );
+ const SocketModeReceiver = await importSocketModeReceiver(overrides);
+
+ const metadata = 'this is bat country';
+ const scopes = ['channels:read'];
+ const userScopes = ['chat:write'];
+ const receiver = new SocketModeReceiver({
+ appToken: 'my-secret',
+ logger: noopLogger,
+ clientId: 'my-clientId',
+ clientSecret: 'my-client-secret',
+ stateSecret: 'state-secret',
+ scopes,
+ installerOptions: {
+ authVersion: 'v2',
+ installPath: '/hiya',
+ renderHtmlForInstallPath: (_) => 'Hello world!',
+ metadata,
+ userScopes,
+ },
+ });
+ assert.isNotNull(receiver);
+ receiver.installer = installProviderStub as unknown as InstallProvider;
+ const fakeReq = {
+ url: '/hiya',
+ };
+ const fakeRes = {
+ writeHead: sinon.fake(),
+ end: sinon.fake(),
+ };
+ /* eslint-disable-next-line @typescript-eslint/await-thenable */
+ await this.listener(fakeReq, fakeRes);
+ assert(installProviderStub.generateInstallUrl.calledWith(sinon.match({ metadata, scopes, userScopes })));
+ assert(fakeRes.writeHead.calledWith(200, sinon.match.object));
+ assert(fakeRes.end.called);
+ assert.isTrue(fakeRes.end.calledWith('Hello world!'));
+ });
  it('should redirect installers if directInstall is true', async function () {
  // Arrange
  const installProviderStub = sinon.createStubInstance(InstallProvider);

src/receivers/SocketModeReceiver.ts

@@ -5,7 +5,7 @@ import { InstallProvider, CallbackOptions, InstallProviderOptions, InstallURLOpt
 import { AppsConnectionsOpenResponse } from '@slack/web-api';
 import App from '../App';
 import { Receiver, ReceiverEvent } from '../types';
-import renderHtmlForInstallPath from './render-html-for-install-path';
+import defaultRenderHtmlForInstallPath from './render-html-for-install-path';
 
 // TODO: we throw away the key names for endpoints, so maybe we should use this interface. is it better for migrations?
 // if that's the reason, let's document that with a comment.
@@ -28,6 +28,7 @@ interface InstallerOptions {
  metadata?: InstallURLOptions['metadata'];
  installPath?: string;
  directInstall?: boolean; // see https://api.slack.com/start/distributing/directory#direct_install
+ renderHtmlForInstallPath?: (url: string) => string;
  redirectUriPath?: string;
  callbackOptions?: CallbackOptions;
  userScopes?: InstallURLOptions['userScopes'];
@@ -118,7 +119,10 @@ export default class SocketModeReceiver implements Receiver {
  res.end('');
  } else {
  res.writeHead(200, {});
- res.end(renderHtmlForInstallPath(url));
+ const renderHtml = installerOptions.renderHtmlForInstallPath !== undefined ?
+ installerOptions.renderHtmlForInstallPath :
+ defaultRenderHtmlForInstallPath;
+ res.end(renderHtml(url));
  }
  } catch (err) {
  const e = err as any;

src/receivers/render-html-for-install-path.ts

@@ -1,4 +1,4 @@
-export default function renderHtmlForInstallPath(addToSlackUrl: string): string {
+export default function defaultRenderHtmlForInstallPath(addToSlackUrl: string): string {
  return `<html>
  <body>
  <a href=${addToSlackUrl}>
@@ -13,3 +13,8 @@ export default function renderHtmlForInstallPath(addToSlackUrl: string): string
  </body>
  </html>`;
 }
+
+// For backward-compatibility
+export function renderHtmlForInstallPath(addToSlackUrl: string): string {
+ return defaultRenderHtmlForInstallPath(addToSlackUrl);
+}