oauth2-cli 0.1.0

package/README.md

@@ -0,0 +1,13 @@
+# oauth2-cli
+
+Acquire API access tokens via OAuth 2.0 within CLI tools
+
+## Install
+
+```sh
+npm i oauth2-cli
+```
+
+## Usage
+
+See [examples/get-token](../../examples/get-token).

package/dist/FileStorage.d.ts

@@ -0,0 +1,9 @@
+import { Token } from './Token.js';
+import { TokenStorage } from './TokenStorage.js';
+export declare class FileStorage implements TokenStorage {
+    private fileLock;
+    private readonly filePath;
+    constructor(filePath: string);
+    load(): Promise<Token | undefined>;
+    save(tokens: Token): Promise<Token>;
+}

package/dist/FileStorage.js

@@ -0,0 +1,29 @@
+import { Mutex } from 'async-mutex';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Token } from './Token.js';
+export class FileStorage {
+    fileLock = new Mutex();
+    filePath;
+    constructor(filePath) {
+        this.filePath = path.resolve(process.cwd(), filePath);
+    }
+    async load() {
+        return await this.fileLock.runExclusive((async () => {
+            if (fs.existsSync(this.filePath)) {
+                return Token.fromResponse(JSON.parse(fs.readFileSync(this.filePath).toString()));
+            }
+            return undefined;
+        }).bind(this));
+    }
+    async save(tokens) {
+        await this.fileLock.runExclusive((async () => {
+            const dirPath = path.dirname(this.filePath);
+            if (!fs.existsSync(dirPath)) {
+                fs.mkdirSync(dirPath, { recursive: true });
+            }
+            fs.writeFileSync(this.filePath, JSON.stringify(tokens));
+        }).bind(this));
+        return tokens;
+    }
+}

package/dist/Localhost.d.ts

@@ -0,0 +1,13 @@
+import * as Configuration from '@battis/oauth2-configure';
+type Options = Configuration.Options & {
+    authorization_url: string;
+    redirect_uri: string;
+    headers?: Record<string, string>;
+    code_verifier?: string;
+    state?: string;
+    resolve: Function;
+    reject: Function;
+    views?: string;
+};
+export declare function redirectServer(options: Options): Promise<void>;
+export {};

package/dist/Localhost.js

@@ -0,0 +1,65 @@
+import * as Configuration from '@battis/oauth2-configure';
+import express from 'express';
+import fs from 'node:fs';
+import path from 'node:path';
+import open from 'open';
+import * as client from 'openid-client';
+export async function redirectServer(options) {
+    const { authorization_url, redirect_uri, code_verifier, state, headers, resolve, reject, views = '../views' } = options;
+    const redirectUrl = new URL(redirect_uri);
+    const configuration = await Configuration.acquire(options);
+    const app = express();
+    const port = redirectUrl.port !== '' ? redirectUrl.port : 80;
+    const server = app.listen(port);
+    const ejs = await import('ejs');
+    let view = 'complete.ejs';
+    let tokens = undefined;
+    let error = undefined;
+    app.get('/authorize', async (req, res) => {
+        let viewPath = path.resolve(import.meta.dirname, views, 'authorize');
+        if (ejs && fs.existsSync(viewPath)) {
+            res.send(await ejs.renderFile(viewPath));
+        }
+        else {
+            res.redirect(authorization_url);
+        }
+    });
+    app.get(redirectUrl.pathname, async (req, res) => {
+        try {
+            const currentUrl = new URL(req.originalUrl, redirect_uri);
+            tokens = await client.authorizationCodeGrant(configuration, currentUrl, {
+                pkceCodeVerifier: code_verifier,
+                expectedState: state
+            }, 
+            // @ts-ignore FIXME undocumented arg pass-through to oauth4webapi
+            { headers });
+        }
+        catch (e) {
+            error = e;
+            view = 'error.ejs';
+        }
+        if (!tokens && !error) {
+            error = 'No tokens received in response to authorization code';
+        }
+        if (ejs) {
+            res.send(await ejs.renderFile(path.resolve(import.meta.dirname, views, view), {
+                tokens,
+                error
+            }));
+        }
+        else {
+            res.send(error || 'You may close this window.');
+        }
+        server.close();
+        if (error) {
+            reject(error);
+        }
+        else {
+            resolve(tokens);
+        }
+    });
+    app.get('*', (_, res) => {
+        res.status(404).send();
+    });
+    open(`http://localhost:${port}/authorize`);
+}

package/dist/Token.d.ts

@@ -0,0 +1,18 @@
+import * as client from 'openid-client';
+interface TokenResponse extends client.TokenEndpointResponse {
+    [key: string]: any;
+}
+export declare class Token implements TokenResponse {
+    readonly access_token: string;
+    readonly token_type: Lowercase<string>;
+    readonly timestamp?: any;
+    readonly refresh_token?: string;
+    readonly refresh_token_expires_in?: number;
+    readonly scope?: string;
+    readonly id_token?: string;
+    readonly expires_in?: number;
+    private constructor();
+    static fromResponse(response?: client.TokenEndpointResponse): Token | undefined;
+    hasExpired(): boolean;
+}
+export {};

package/dist/Token.js

@@ -0,0 +1,26 @@
+export class Token {
+    access_token;
+    token_type;
+    timestamp;
+    refresh_token;
+    refresh_token_expires_in;
+    scope;
+    id_token;
+    expires_in;
+    constructor(response) {
+        this.access_token = response.access_token;
+        this.token_type = response.token_type;
+        this.timestamp = response.timestamp;
+        Object.assign(this, response);
+    }
+    static fromResponse(response) {
+        if (response) {
+            return new Token({ timestamp: Date.now(), ...response });
+        }
+        return undefined;
+    }
+    hasExpired() {
+        return (this.expires_in === undefined ||
+            Date.now() > this.timestamp + this.expires_in);
+    }
+}

package/dist/TokenManager.d.ts

@@ -0,0 +1,18 @@
+import * as Configuration from '@battis/oauth2-configure';
+import { Token } from './Token.js';
+import { TokenStorage } from './TokenStorage.js';
+export type Options = Configuration.Options & {
+    scope?: string;
+    headers?: Record<string, string>;
+    parameters?: Record<string, string>;
+    store?: TokenStorage | string;
+};
+export declare class TokenManager {
+    private options;
+    private tokenMutex;
+    private store?;
+    constructor(options: Options);
+    getToken(): Promise<Token | undefined>;
+    private refreshToken;
+    private authorize;
+}

package/dist/TokenManager.js

@@ -0,0 +1,79 @@
+import * as Configuration from '@battis/oauth2-configure';
+import { Mutex } from 'async-mutex';
+import * as client from 'openid-client';
+import { FileStorage } from './FileStorage.js';
+import * as Localhost from './Localhost.js';
+import { Token } from './Token.js';
+export class TokenManager {
+    options;
+    tokenMutex = new Mutex();
+    store;
+    constructor(options) {
+        this.options = options;
+        if (this.options.store) {
+            if (typeof this.options.store === 'string') {
+                this.store = new FileStorage(this.options.store);
+            }
+            else {
+                this.store = this.options.store;
+            }
+        }
+    }
+    async getToken() {
+        return await this.tokenMutex.runExclusive((async () => {
+            let token = await this.store?.load();
+            if (token?.hasExpired()) {
+                token = await this.refreshToken(token);
+            }
+            return token || (await this.authorize());
+        }).bind(this));
+    }
+    async refreshToken(token) {
+        if (token.refresh_token) {
+            const { headers, parameters } = this.options;
+            let freshTokens;
+            if ((freshTokens = Token.fromResponse(await client.refreshTokenGrant(await Configuration.acquire(this.options), token.refresh_token, parameters, 
+            // @ts-ignore FIXME undocumented arg pass-through to oauth4webapi
+            { headers })))) {
+                return this.store?.save(freshTokens) || freshTokens;
+            }
+        }
+        return this.authorize();
+    }
+    async authorize() {
+        const { scope, redirect_uri, parameters: additionalParameters } = this.options;
+        return new Promise(async (resolve, reject) => {
+            const configuration = await Configuration.acquire(this.options);
+            const code_verifier = client.randomPKCECodeVerifier();
+            const code_challenge = await client.calculatePKCECodeChallenge(code_verifier);
+            let state = undefined;
+            const parameters = {
+                ...additionalParameters,
+                redirect_uri,
+                code_challenge,
+                code_challenge_method: 'S256' // TODO make code challenge method configurable?
+            };
+            if (scope) {
+                parameters.scope = scope;
+            }
+            if (!configuration.serverMetadata().supportsPKCE()) {
+                state = client.randomState();
+                parameters.state = state;
+            }
+            await Localhost.redirectServer({
+                ...this.options,
+                authorization_url: client.buildAuthorizationUrl(configuration, parameters).href,
+                code_verifier,
+                state,
+                resolve: (async (response) => {
+                    const token = Token.fromResponse(response);
+                    if (token && this.store) {
+                        await this.store.save(token);
+                    }
+                    resolve(token);
+                }).bind(this),
+                reject
+            });
+        });
+    }
+}

package/dist/TokenStorage.d.ts

@@ -0,0 +1,5 @@
+import { Token } from './Token.js';
+export interface TokenStorage {
+    load(): Promise<Token | undefined>;
+    save(tokens: Token): Promise<Token>;
+}

package/dist/TokenStorage.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { FileStorage } from './FileStorage.js';
+export { Token } from './Token.js';
+export { TokenManager } from './TokenManager.js';
+export { TokenStorage } from './TokenStorage.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { FileStorage } from './FileStorage.js';
+export { Token } from './Token.js';
+export { TokenManager } from './TokenManager.js';

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "oauth2-cli",
+  "version": "0.1.0",
+  "description": "Acquire API access tokens via OAuth 2.0 within CLI tools",
+  "homepage": "https://github.com/battis/oauth-cli/tree/main/packages/oauth2-cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/battis/oauth-cli.git",
+    "directory": "packages/oauth2-cli"
+  },
+  "author": {
+    "name": "Seth Battis",
+    "url": "https://github.com/battis"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "async-mutex": "^0.5.0",
+    "express": "^4.21.1",
+    "openid-client": "^6.1.3",
+    "@battis/oauth2-configure": "0.1.0"
+  },
+  "devDependencies": {
+    "@tsconfig/node20": "^20.1.4",
+    "@types/ejs": "^3.1.5",
+    "@types/express": "^5.0.0",
+    "del-cli": "^6.0.0",
+    "npm-run-all": "^4.1.5",
+    "open": "^10.1.0",
+    "typescript": "^5.6.3"
+  },
+  "peerDependencies": {
+    "ejs": "*"
+  },
+  "peerDependencyMeta": {
+    "ejs": {
+      "optional": true
+    }
+  },
+  "repo": {
+    "type": "git",
+    "url": "https://github.com/battis/oauth2-cli.git"
+  },
+  "scripts": {
+    "clean": "del ./dist",
+    "build": "run-s build:*",
+    "build:clean": "run-s clean",
+    "build:compile": "tsc"
+  }
+}

package/src/FileStorage.ts

@@ -0,0 +1,40 @@
+import { Mutex } from 'async-mutex';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Token } from './Token.js';
+import { TokenStorage } from './TokenStorage.js';
+
+export class FileStorage implements TokenStorage {
+  private fileLock = new Mutex();
+  private readonly filePath: string;
+
+  public constructor(filePath: string) {
+    this.filePath = path.resolve(process.cwd(), filePath);
+  }
+
+  public async load() {
+    return await this.fileLock.runExclusive(
+      (async () => {
+        if (fs.existsSync(this.filePath)) {
+          return Token.fromResponse(
+            JSON.parse(fs.readFileSync(this.filePath).toString())
+          );
+        }
+        return undefined;
+      }).bind(this)
+    );
+  }
+
+  public async save(tokens: Token) {
+    await this.fileLock.runExclusive(
+      (async () => {
+        const dirPath = path.dirname(this.filePath);
+        if (!fs.existsSync(dirPath)) {
+          fs.mkdirSync(dirPath, { recursive: true });
+        }
+        fs.writeFileSync(this.filePath, JSON.stringify(tokens));
+      }).bind(this)
+    );
+    return tokens;
+  }
+}

package/src/Localhost.ts

@@ -0,0 +1,92 @@
+import * as Configuration from '@battis/oauth2-configure';
+import express from 'express';
+import fs from 'node:fs';
+import path from 'node:path';
+import open from 'open';
+import * as client from 'openid-client';
+
+type Options = Configuration.Options & {
+  authorization_url: string;
+  redirect_uri: string;
+  headers?: Record<string, string>;
+  code_verifier?: string;
+  state?: string;
+  resolve: Function;
+  reject: Function;
+  views?: string;
+};
+
+export async function redirectServer(options: Options) {
+  const {
+    authorization_url,
+    redirect_uri,
+    code_verifier,
+    state,
+    headers,
+    resolve,
+    reject,
+    views = '../views'
+  } = options;
+  const redirectUrl = new URL(redirect_uri);
+
+  const configuration = await Configuration.acquire(options);
+
+  const app = express();
+  const port = redirectUrl.port !== '' ? redirectUrl.port : 80;
+  const server = app.listen(port);
+  const ejs = await import('ejs');
+  let view = 'complete.ejs';
+  let tokens: client.TokenEndpointResponse | undefined = undefined;
+  let error: any = undefined;
+
+  app.get('/authorize', async (req, res) => {
+    let viewPath = path.resolve(import.meta.dirname, views, 'authorize');
+    if (ejs && fs.existsSync(viewPath)) {
+      res.send(await ejs.renderFile(viewPath));
+    } else {
+      res.redirect(authorization_url);
+    }
+  });
+  app.get(redirectUrl.pathname, async (req, res) => {
+    try {
+      const currentUrl = new URL(req.originalUrl, redirect_uri);
+      tokens = await client.authorizationCodeGrant(
+        configuration,
+        currentUrl,
+        {
+          pkceCodeVerifier: code_verifier,
+          expectedState: state
+        },
+        // @ts-ignore FIXME undocumented arg pass-through to oauth4webapi
+        { headers }
+      );
+    } catch (e) {
+      error = e;
+      view = 'error.ejs';
+    }
+    if (!tokens && !error) {
+      error = 'No tokens received in response to authorization code';
+    }
+    if (ejs) {
+      res.send(
+        await ejs.renderFile(path.resolve(import.meta.dirname, views, view), {
+          tokens,
+          error
+        })
+      );
+    } else {
+      res.send(error || 'You may close this window.');
+    }
+    server.close();
+    if (error) {
+      reject(error);
+    } else {
+      resolve(tokens);
+    }
+  });
+  app.get('*', (_, res) => {
+    res.status(404).send();
+  });
+
+  open(`http://localhost:${port}/authorize`);
+}

package/src/Token.ts

@@ -0,0 +1,37 @@
+import * as client from 'openid-client';
+
+interface TokenResponse extends client.TokenEndpointResponse {
+  [key: string]: any;
+}
+
+export class Token implements TokenResponse {
+  public readonly access_token: string;
+  public readonly token_type: Lowercase<string>;
+  public readonly timestamp?: any;
+  public readonly refresh_token?: string;
+  public readonly refresh_token_expires_in?: number;
+  public readonly scope?: string;
+  public readonly id_token?: string;
+  public readonly expires_in?: number;
+
+  private constructor(response: client.TokenEndpointResponse) {
+    this.access_token = response.access_token;
+    this.token_type = response.token_type;
+    this.timestamp = response.timestamp;
+    Object.assign(this, response);
+  }
+
+  public static fromResponse(response?: client.TokenEndpointResponse) {
+    if (response) {
+      return new Token({ timestamp: Date.now(), ...response });
+    }
+    return undefined;
+  }
+
+  public hasExpired() {
+    return (
+      this.expires_in === undefined ||
+      Date.now() > this.timestamp + this.expires_in
+    );
+  }
+}

package/src/TokenManager.ts

@@ -0,0 +1,111 @@
+import * as Configuration from '@battis/oauth2-configure';
+import { Mutex } from 'async-mutex';
+import open from 'open';
+import * as client from 'openid-client';
+import { FileStorage } from './FileStorage.js';
+import * as Localhost from './Localhost.js';
+import { Token } from './Token.js';
+import { TokenStorage } from './TokenStorage.js';
+
+export type Options = Configuration.Options & {
+  scope?: string;
+  headers?: Record<string, string>;
+  parameters?: Record<string, string>;
+  store?: TokenStorage | string;
+};
+
+export class TokenManager {
+  private tokenMutex = new Mutex();
+  private store?: TokenStorage;
+
+  public constructor(private options: Options) {
+    if (this.options.store) {
+      if (typeof this.options.store === 'string') {
+        this.store = new FileStorage(this.options.store);
+      } else {
+        this.store = this.options.store;
+      }
+    }
+  }
+
+  public async getToken() {
+    return await this.tokenMutex.runExclusive(
+      (async () => {
+        let token = await this.store?.load();
+        if (token?.hasExpired()) {
+          token = await this.refreshToken(token);
+        }
+        return token || (await this.authorize());
+      }).bind(this)
+    );
+  }
+
+  private async refreshToken(token: Token): Promise<Token | undefined> {
+    if (token.refresh_token) {
+      const { headers, parameters } = this.options;
+      let freshTokens;
+      if (
+        (freshTokens = Token.fromResponse(
+          await client.refreshTokenGrant(
+            await Configuration.acquire(this.options),
+            token.refresh_token,
+            parameters,
+            // @ts-ignore FIXME undocumented arg pass-through to oauth4webapi
+            { headers }
+          )
+        ))
+      ) {
+        return this.store?.save(freshTokens) || freshTokens;
+      }
+    }
+    return this.authorize();
+  }
+
+  private async authorize(): Promise<Token | undefined> {
+    const {
+      scope,
+      redirect_uri,
+      parameters: additionalParameters
+    } = this.options;
+
+    return new Promise(async (resolve, reject) => {
+      const configuration = await Configuration.acquire(this.options);
+      const code_verifier = client.randomPKCECodeVerifier();
+      const code_challenge =
+        await client.calculatePKCECodeChallenge(code_verifier);
+      let state: string | undefined = undefined;
+      const parameters: Record<string, string> = {
+        ...additionalParameters,
+        redirect_uri,
+        code_challenge,
+        code_challenge_method: 'S256' // TODO make code challenge method configurable?
+      };
+
+      if (scope) {
+        parameters.scope = scope;
+      }
+      if (!configuration.serverMetadata().supportsPKCE()) {
+        state = client.randomState();
+        parameters.state = state;
+      }
+
+      await Localhost.redirectServer({
+        ...this.options,
+        authorization_url: client.buildAuthorizationUrl(
+          configuration,
+          parameters
+        ).href,
+        code_verifier,
+        state,
+        resolve: (async (response: client.TokenEndpointResponse) => {
+          const token = Token.fromResponse(response);
+          if (token && this.store) {
+            await this.store.save(token);
+          }
+          resolve(token);
+        }).bind(this),
+        reject
+      });
+    });
+  }
+}

package/src/TokenStorage.ts

@@ -0,0 +1,6 @@
+import { Token } from './Token.js';
+
+export interface TokenStorage {
+  load(): Promise<Token | undefined>;
+  save(tokens: Token): Promise<Token>;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { FileStorage } from './FileStorage.js';
+export { Token } from './Token.js';
+export { TokenManager } from './TokenManager.js';
+export { TokenStorage } from './TokenStorage.js';

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@tsconfig/node20/tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "declaration": true
+  },
+  "include": ["./src"]
+}