Add support for auth tokens

- Introduce new config option `authToken`
- Expect either username/password *or* auth token
- Carry out necessary modifications of types and function signatures to account for either/or logic
- (Still) Prompt for username/password if neither user/pass *nor* auth token is given
- Adapt tests
- Update README

Author: Simon Hirscher

README.md

@@ -49,9 +49,10 @@ which produces:
 
 ```json
 {
-  "baseUrl": "YOUR_BASE_URL",
-  "user": "YOUR_USERNAME",
-  "pass": "YOUR_PASSWORD",
+  "baseUrl": "<your base URL>",
+  "user": "<your username>",
+  "pass": "<your password>",
+  "authToken": "<your auth token (can be set instead of username/password)>",
   "cachePath": "build",
   "prefix": "This document is automatically generated. Please don't edit it directly!",
   "pages": [
@@ -69,14 +70,22 @@ which produces:
 In most scenarios it is not recommended to store your credentials in the configuration file, because you will probably add it to your VCS. Instead it is recommended to provide the following environment variables in your build pipeline (GitLab CI, GitHub Actions, Jenkins, ...):
 
 ```ini
-CONFLUENCE_USERNAME=YOUR_USERNAME
-CONFLUENCE_PASSWORD=YOUR_PASSWORD
+CONFLUENCE_USERNAME="<your username>"
+CONFLUENCE_PASSWORD="<your password>"
+```
+
+or
+
+```ini
+CONFLUENCE_AUTH_TOKEN="<your auth token>"
 ```
 
 or add it in front of the command when executing locally (add a space in front of the command when using bash in order to not write the credentials to the bash history):
 
 ```bash
- CONFLUENCE_USER=YOUR_USERNAME CONFLUENCE_PASSWORD=YOUR_PASSWORD cosmere
+ CONFLUENCE_USER="<your username>" CONFLUENCE_PASSWORD="<your password>" cosmere
+# or
+ CONFLUENCE_AUTH_TOKEN="<your auth token>" cosmere
 ```
 
 ### Run

src/ConfigLoader.ts

@@ -1,61 +1,80 @@
 import * as path from "path";
 import * as fs from "fs";
-import { Config } from "./types/Config";
+import { Config, ConfigKey, isBasicAuth, isTokenAuth } from "./types/Config";
 import * as inquirer from "inquirer";
 import signale from "signale";
 
+
+function overwriteConfigKeyWithEnvVarIfPresent<T>(config: Partial<Config>, configKey: ConfigKey, envKey: string): Partial<Config> {
+    if (configKey === "pages") {
+        throw Error("Cannot override pages using environment variable");
+    }
+
+    if (process.env[envKey] !== undefined) {
+        return { ...config, [configKey]: process.env[envKey] };
+    } else {
+        return config;
+    }
+}
+
+
 export class ConfigLoader {
-    static async load(configPath: string | null): Promise<Config> {
-        return await ConfigLoader.promptUserAndPassIfNotSet(
-            ConfigLoader.overwriteAuthFromConfigWithEnvIfPresent(ConfigLoader.readConfigFromFile(configPath)),
-        );
+    static async load(configPath: string | null): Promise<Partial<Config>> {
+        let config = ConfigLoader.readConfigFromFile(configPath);
+        config = ConfigLoader.overwriteAuthFromConfigWithEnvIfPresent(config),
+        config = await ConfigLoader.promptUserAndPassIfNoCredentialsSet(config);
+        return config;
     }
 
-    private static readConfigFromFile(configPath: string | null): Config {
+    private static readConfigFromFile(configPath: string | null): Partial<Config> {
         configPath = path.resolve(configPath || path.join("cosmere.json"));
         if (!fs.existsSync(configPath!)) {
             signale.fatal(`File "${configPath}" not found!`);
             process.exit(1);
         }
 
-        let config = JSON.parse(fs.readFileSync(configPath!, "utf8")) as Config;
-        for (const i in config.pages) {
-            config.pages[i].file = path.isAbsolute(config.pages[i].file)
-                ? config.pages[i].file
-                : path.resolve(path.dirname(configPath) + "/" + config.pages[i].file);
+        let config: Partial<Config> = JSON.parse(fs.readFileSync(configPath!, "utf8"));
+        if (config.pages !== undefined) {
+            for (const i in config.pages) {
+                config.pages[i].file = path.isAbsolute(config.pages[i].file)
+                    ? config.pages[i].file
+                    : path.resolve(path.dirname(configPath) + "/" + config.pages[i].file);
+            }
         }
         config.configPath = configPath;
         return config;
     }
 
-    private static overwriteAuthFromConfigWithEnvIfPresent(config: Config): Config {
-        config.user = process.env.CONFLUENCE_USERNAME || config.user;
-        config.pass = process.env.CONFLUENCE_PASSWORD || config.pass;
+    private static overwriteAuthFromConfigWithEnvIfPresent(config: Partial<Config>): Partial<Config> {
+        config = overwriteConfigKeyWithEnvVarIfPresent(config, "user", "CONFLUENCE_USERNAME");
+        config = overwriteConfigKeyWithEnvVarIfPresent(config, "pass", "CONFLUENCE_PASSWORD");
+        config = overwriteConfigKeyWithEnvVarIfPresent(config, "authToken", "CONFLUENCE_AUTH_TOKEN");
         return config;
     }
 
-    private static async promptUserAndPassIfNotSet(config: Config): Promise<Config> {
-        const prompts = [];
-        if (!config.user) {
-            prompts.push({
+    private static async promptUserAndPassIfNoCredentialsSet(config: Partial<Config>): Promise<Partial<Config>> {
+        if (isTokenAuth(config)) {
+            return config;
+        }
+
+        if (!("user" in config)) {
+            const answers = await inquirer.prompt([{
                 type: "input",
                 name: "user",
                 message: "Your Confluence username:",
-            });
+            }]);
+            (config as any).user = answers.user;
         }
 
-        if (!config.pass) {
-            prompts.push({
+        if (!("pass" in config)) {
+            const answers = await inquirer.prompt([{
                 type: "password",
                 name: "pass",
                 message: "Your Confluence password:",
-            });
+            }]);
+            (config as any).pass = answers.pass;
         }
 
-        const answers = await inquirer.prompt(prompts);
-        config.user = config.user || (answers.user as string);
-        config.pass = config.pass || (answers.pass as string);
-
         return config;
     }
 }

src/api/ConfluenceAPI.ts

@@ -1,29 +1,22 @@
-import { AuthHeaders } from "../types/AuthHeaders";
-import axios from "axios";
+import { AuthConfig, isBasicAuth, isTokenAuth } from "../types/Config";
+import axios, { AxiosRequestConfig } from "axios";
 import * as fs from "fs";
 import signale from "signale";
 
-export class ConfluenceAPI {
-    private readonly authHeaders: AuthHeaders;
-    private readonly baseUrl: string;
 
-    constructor(baseUrl: string, username: string, password: string) {
-        this.baseUrl = baseUrl;
-        this.authHeaders = {
-            auth: {
-                username: username,
-                password: password,
-            },
-        };
-    }
+export class ConfluenceAPI {
+    constructor(
+        private readonly baseUrl: string,
+        private readonly authConfig: AuthConfig
+    ) {}
 
     async updateConfluencePage(pageId: string, newPage: any) {
-        const config = {
+        const config = this.appendAuthHeaders({
             headers: {
                 "Content-Type": "application/json",
             },
-            ...this.authHeaders,
-        };
+        });
+
         try {
             await axios.put(`${this.baseUrl}/content/${pageId}`, newPage, config);
         } catch (e) {
@@ -33,11 +26,12 @@ export class ConfluenceAPI {
     }
 
     async deleteAttachments(pageId: string) {
-        const attachments = await axios.get(`${this.baseUrl}/content/${pageId}/child/attachment`, this.authHeaders);
+        const config = this.appendAuthHeaders({});
+        const attachments = await axios.get(`${this.baseUrl}/content/${pageId}/child/attachment`, config);
         for (const attachment of attachments.data.results) {
             try {
                 signale.await(`Deleting attachment "${attachment.title}" ...`);
-                await axios.delete(`${this.baseUrl}/content/${attachment.id}`, this.authHeaders);
+                await axios.delete(`${this.baseUrl}/content/${attachment.id}`, config);
             } catch (e) {
                 signale.error(`Deleting attachment "${attachment.title}" failed ...`);
             }
@@ -46,7 +40,7 @@ export class ConfluenceAPI {
 
     async uploadAttachment(filename: string, pageId: string) {
         try {
-            await require("axios-file")({
+            const config = this.appendAuthHeaders({
                 url: `${this.baseUrl}/content/${pageId}/child/attachment`,
                 method: "post",
                 headers: {
@@ -55,14 +49,40 @@ export class ConfluenceAPI {
                 data: {
                     file: fs.createReadStream(filename),
                 },
-                ...this.authHeaders,
             });
+
+            await require("axios-file")(config);
         } catch (e) {
             signale.error(`Uploading attachment "${filename}" failed ...`);
         }
     }
 
     async currentPage(pageId: string) {
-        return axios.get(`${this.baseUrl}/content/${pageId}?expand=body.storage,version`, this.authHeaders);
+        const config = this.appendAuthHeaders({});
+        return axios.get(`${this.baseUrl}/content/${pageId}?expand=body.storage,version`, config);
+    }
+
+    private appendAuthHeaders(config: AxiosRequestConfig): AxiosRequestConfig {
+        if (isBasicAuth(this.authConfig)) {
+            return {
+                ...config,
+                auth: {
+                    username: this.authConfig.user,
+                    password: this.authConfig.pass,
+                },
+            };
+        }
+        else if (isTokenAuth(this.authConfig)) {
+            return {
+                ...config,
+                headers: {
+                    ...(config.headers ?? {}),
+                    "Authorization": `Bearer ${this.authConfig.authToken}`,
+                }
+            }
+        }
+        else {
+            throw Error("No credentials found in config");
+        }
     }
 }

src/cli/GenerateCommand.ts

@@ -5,9 +5,10 @@ export default function(configPath: string | null) {
     fs.writeFileSync(
         configPath || path.join("cosmere.json")!,
         `{
-  "baseUrl": "YOUR_BASE_URL",
-  "user": "YOUR_USERNAME",
-  "pass": "YOUR_PASSWORD",
+  "baseUrl": "<your base URL>",
+  "user": "<your username>",
+  "pass": "<your password>",
+  "authToken": "<your auth token (can be set instead of username/password)>",
   "cachePath": "build",
   "prefix": "This document is automatically generated. Please don't edit it directly!",
   "pages": [

src/cli/MainCommand.ts

@@ -4,8 +4,8 @@ import { ConfluenceAPI } from "../api/ConfluenceAPI";
 import { updatePage } from "../UpdatePage";
 
 export default async function(configPath: string | null, force: boolean = false) {
-    const config: Config = await ConfigLoader.load(configPath);
-    const confluenceAPI = new ConfluenceAPI(config.baseUrl, config.user!, config.pass!);
+    const config: Config = await ConfigLoader.load(configPath) as Config;
+    const confluenceAPI = new ConfluenceAPI(config.baseUrl, config);
 
     for (const pageData of config.pages) {
         await updatePage(confluenceAPI, pageData, config, force);

src/types/AuthHeaders.ts

@@ -1,11 +1,30 @@
 import { Page } from "./Page";
 
-export type Config = {
+export type BasicAuthConfig = {
+    user: string;
+    pass: string;
+};
+
+export type TokenAuthConfig = {
+    authToken: string;
+};
+
+export type AuthConfig = BasicAuthConfig | TokenAuthConfig;
+
+export type Config = AuthConfig & {
     baseUrl: string;
     cachePath: string;
-    user?: string;
-    pass?: string;
-    prefix: string;
+    prefix?: string;
     pages: Page[];
     configPath: string | null;
 };
+
+export type ConfigKey = keyof BasicAuthConfig | keyof TokenAuthConfig | keyof Config;
+
+export function isBasicAuth(authConfig: Object): authConfig is BasicAuthConfig {
+    return authConfig.hasOwnProperty("user");
+}
+
+export function isTokenAuth(authConfig: Object): authConfig is TokenAuthConfig {
+    return authConfig.hasOwnProperty("authToken");
+}

src/types/Config.ts

@@ -10,12 +10,14 @@ describe("UpdatePage", () => {
       file: "/dev/null"
     };
     const config: Config = {
+      user: "",
+      pass: "",
       baseUrl: "string",
       cachePath: "string",
       prefix: "string",
       pages: [],
       configPath: null,
     };
-    expect(updatePage(new ConfluenceAPI("", "", ""), pageData, config, false)).toBeFalsy();
+    expect(updatePage(new ConfluenceAPI("", config), pageData, config, false)).toBeFalsy();
   });
 });

tests/UpdatePage.test.ts

@@ -6,10 +6,10 @@ jest.mock('axios');
 const axiosMock = mocked(axios, true);
 
 describe("ConfluenceAPI", () => {
-  it("fetches current version of confluence page", async () => {
+  it("fetches current version of confluence page using basic auth", async () => {
     axiosMock.get.mockResolvedValue({ data: "Test"});
 
-    const confluenceAPI = new ConfluenceAPI("", "", "");
+    const confluenceAPI = new ConfluenceAPI("", { user: "", pass: "" });
     await confluenceAPI.currentPage("2");
     expect(axiosMock.get).toHaveBeenCalledWith(
       "/content/2?expand=body.storage,version",
@@ -21,4 +21,20 @@ describe("ConfluenceAPI", () => {
       }
     );
   });
+
+  it("fetches current version of confluence page using auth token", async () => {
+    axiosMock.get.mockResolvedValue({ data: "Test"});
+
+    const authToken = "foo";
+    const confluenceAPI = new ConfluenceAPI("", { authToken });
+    await confluenceAPI.currentPage("2");
+    expect(axiosMock.get).toHaveBeenCalledWith(
+      "/content/2?expand=body.storage,version",
+      {
+        headers: {
+          Authorization: `Bearer ${authToken}`,
+        }
+      }
+    );
+  });
 });

tests/api/ConfluenceAPI.test.ts

@@ -7,9 +7,10 @@ describe("GenerateCommand", () => {
     const path = os.tmpdir() + '/cosmere.json';
     GenerateCommand(path);
     expect(fs.readFileSync(path, "utf8")).toBe(`{
-  "baseUrl": "YOUR_BASE_URL",
-  "user": "YOUR_USERNAME",
-  "pass": "YOUR_PASSWORD",
+  "baseUrl": "<your base URL>",
+  "user": "<your username>",
+  "pass": "<your password>",
+  "authToken": "<your auth token (can be set instead of username/password)>",
   "cachePath": "build",
   "prefix": "This document is automatically generated. Please don't edit it directly!",
   "pages": [