oauth2-cli 0.8.8 → 1.0.0

package/dist/Localhost/Server.js

@@ -0,0 +1,175 @@
+import { Colors } from '@qui-cli/colors';
+import express from 'express';
+import * as gcrtl from 'gcrtl';
+import fs from 'node:fs';
+import open from 'open';
+import * as OpenIDClient from 'openid-client';
+import ora from 'ora';
+import path from 'path';
+import { URL } from 'requestish';
+import { DEFAULT_LAUNCH_ENDPOINT } from './Defaults.js';
+let ejs = undefined;
+try {
+    ejs = (await import('ejs')).default;
+}
+catch (_) {
+    // ejs peer dependency not installed
+}
+/**
+ * Minimal HTTP server running on localhost to handle the redirect step of
+ * OpenID/OAuth flows
+ */
+export class Server {
+    static activePorts = [];
+    /** PKCE code_verifier */
+    code_verifier = OpenIDClient.randomPKCECodeVerifier();
+    /** OAuth 2.0 state (if PKCE is not supported) */
+    state = OpenIDClient.randomState();
+    client;
+    reason = 'an unnamed oauth2-cli app';
+    views;
+    packageViews = '../../views';
+    spinner;
+    port;
+    launch_endpoint;
+    server;
+    resolveAuthorizationCodeFlow = undefined;
+    rejectAuthorizationCodeFlow = undefined;
+    constructor({ reason, client, views, launch_endpoint = DEFAULT_LAUNCH_ENDPOINT, timeout = 1000 // milliseconds
+     }) {
+        this.client = client;
+        this.reason = reason || this.reason;
+        this.spinner = ora(`Awaiting interactive authorization for ${this.client.name} access by ${this.reason}`).start();
+        this.launch_endpoint = launch_endpoint;
+        this.views = views;
+        const url = URL.from(this.client.credentials.redirect_uri);
+        this.port = url.port;
+        if (Server.activePorts.includes(this.port)) {
+            throw new Error(`Another process is already running at http://localhost:${url.port}.`, { cause: { activePorts: Server.activePorts } });
+        }
+        Server.activePorts.push(this.port);
+        const app = express();
+        app.get(this.launch_endpoint, this.handleAuthorizationEndpoint.bind(this));
+        app.get(gcrtl.path(url), this.handleRedirect.bind(this));
+        this.server = app.listen(gcrtl.port(url));
+        this.server.timeout = timeout;
+        this.server.keepAliveTimeout = 0;
+        this.server.keepAliveTimeoutBuffer = 0;
+    }
+    async authorizationCodeGrant() {
+        const response = new Promise((resolve, reject) => {
+            this.resolveAuthorizationCodeFlow = resolve;
+            this.rejectAuthorizationCodeFlow = reject;
+        });
+        const url = URL.toString(gcrtl.expand(this.launch_endpoint, this.client.credentials.redirect_uri));
+        open(url, { wait: false });
+        this.spinner.text = `Please continue interactive authorization of ${this.client.name} for ${this.reason} at ${Colors.url(url)} in your browser`;
+        await response;
+        this.spinner.text = `Waiting for ${this.client.name} localhost redirect server to shut down`;
+        await this.close();
+        return response;
+    }
+    /**
+     * Set the path to folder of *.ejs templates
+     *
+     * Expected templates include:
+     *
+     * - `launch.ejs` presents information prior to the authorization to the user,
+     *   and the user must follow `authorize_url` data property to interactively
+     *   launch authorization
+     * - `complete.ejs` presented to user upon successful completion of
+     *   authorization flow
+     * - `error.ejs` presented to user upon receipt of an error from the server,
+     *   includes `error` as data
+     *
+     * `complete.ejs` and `error.ejs` are included with oauth2-cli and those
+     * templates will be used if `ejs` is imported but no replacement templates
+     * are found.
+     *
+     * All views receive a data property `name` which is the human-readable name
+     * of the Client managing the authorization code flow, and `reason` indicating
+     * the human-readable reason (i.e. name of the app) requesting authorization,
+     * which should be displayed in messages for transparency.
+     *
+     * @param views Should be an absolute path
+     */
+    setViews(views) {
+        this.views = views;
+    }
+    async render(res, template, data = {}) {
+        const name = this.client.name;
+        const reason = this.reason;
+        async function attemptToRender(views) {
+            if (ejs && views) {
+                const viewPath = path.resolve(import.meta.dirname, views, template);
+                if (fs.existsSync(viewPath)) {
+                    res.send(await ejs.renderFile(viewPath, {
+                        name,
+                        reason,
+                        ...data
+                    }));
+                    return true;
+                }
+            }
+            return false;
+        }
+        return ((await attemptToRender(this.views)) ||
+            (await attemptToRender(this.packageViews)));
+    }
+    /** Handles request to `/authorize` */
+    async handleAuthorizationEndpoint(req, res) {
+        const authorization_url = URL.toString(await this.client.buildAuthorizationUrl(this));
+        if (!(await this.render(res, 'launch.ejs', { authorization_url }))) {
+            res.redirect(authorization_url);
+            res.end();
+        }
+    }
+    /** Handles request to `redirect_uri` */
+    async handleRedirect(req, res) {
+        this.spinner.text = `Exchanging authorization code for ${this.client.name} access token for ${this.reason}`;
+        try {
+            if (this.resolveAuthorizationCodeFlow) {
+                this.resolveAuthorizationCodeFlow(await this.client.handleAuthorizationCodeRedirect(req, this));
+                this.spinner.text = `${this.client.name} authorization complete and access token received for ${this.reason}`;
+                if (!(await this.render(res, 'complete.ejs'))) {
+                    res.send(`${this.client.name} authorization complete for ${this.reason}. You may close this window.`);
+                }
+            }
+            else {
+                throw new Error(`${this.client.name} localhost redirect session resolver is ${this.resolveAuthorizationCodeFlow}`);
+            }
+        }
+        catch (error) {
+            if (this.rejectAuthorizationCodeFlow) {
+                this.rejectAuthorizationCodeFlow(new Error(`${this.client.name} localhost server could not handle redirect`, {
+                    cause: error
+                }));
+            }
+            if (!(await this.render(res, 'error.ejs', { error }))) {
+                res.send({
+                    client: this.client.name,
+                    error
+                });
+            }
+        }
+    }
+    /** Shut down web server */
+    async close() {
+        return new Promise((resolve, reject) => {
+            this.server.close((cause) => {
+                if (cause) {
+                    const message = `Error shutting down ${this.client.name} localhost redirect server`;
+                    this.spinner.fail(`Error shutting down ${this.client.name} localhost redirect server`);
+                    reject(new Error(message, {
+                        cause
+                    }));
+                }
+                else {
+                    Server.activePorts.splice(Server.activePorts.indexOf(this.port), 1);
+                    this.spinner.succeed(`${this.client.name} authorization complete for ${this.reason}`);
+                    resolve();
+                }
+            });
+        });
+    }
+}

package/dist/Localhost/index.d.ts

@@ -0,0 +1,3 @@
+export * from './Defaults.js';
+export * from './Options.js';
+export * from './Server.js';

package/dist/Localhost/index.js

@@ -0,0 +1,3 @@
+export * from './Defaults.js';
+export * from './Options.js';
+export * from './Server.js';

package/dist/Options.d.ts

@@ -0,0 +1,54 @@
+import { URL } from 'requestish';
+import { Credentials } from './Credentials.js';
+import { Injection } from './Injection.js';
+import * as Localhost from './Localhost/index.js';
+import * as Token from './Token/index.js';
+/** For use only within the Client implementation */
+export type LocalhostOptions = Omit<Localhost.Options, 'client' | 'reason'>;
+export type Client<C extends Credentials = Credentials> = {
+    /** Human-readable name for client in messages (e.g. the name of the API) */
+    name?: string;
+    /**
+     * Human-readable reason for authorizing access in messages (e.g. the app
+     * name)
+     */
+    reason?: string;
+    /** Credentials for server access */
+    credentials: C;
+    /** Optional request components to inject */
+    inject?: Injection;
+    /** Base URL for all non-absolute requests */
+    base_url?: URL.ish;
+    /** Optional {@link TokenStorage} implementation to manage tokens */
+    storage?: Token.Storage;
+    /**
+     * Optional configuration for localhost web server listening for authorization
+     * code redirect
+     */
+    localhost?: LocalhostOptions;
+};
+export type Refresh = {
+    /**
+     * Optional refresh token
+     *
+     * If using {@link TokenStorage}, the refresh token should be stored with the
+     * access token and does not need to be separately managed and stored
+     */
+    refresh_token?: string;
+    /** Additional request injection for refresh grant flow */
+    inject?: Injection;
+};
+export type GetToken = {
+    /**
+     * Optional access token
+     *
+     * If using {@link TokenStorage}, the access token does not need to be
+     * separately managed and stored
+     */
+    token?: Token.Response;
+    /**
+     * Additional request injection for authorization code grant and/or refresh
+     * grant flows
+     */
+    inject?: Injection;
+};

package/dist/Options.js

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

package/dist/Token/FileStorage.d.ts

@@ -1,7 +1,22 @@
 import { Storage } from './Storage.js';
+/**
+ * Save a refresh token to a specific file
+ *
+ * Care _must_ be taken when using this persistence strategy that:
+ *
+ * 1. The token file is not publicly accessible
+ * 2. The token file is _not_ commited to a public repository
+ *
+ * This strategy is appropriate only in very limited set of use cases.
+ */
 export declare class FileStorage implements Storage {
+    /** Prevent multiple simultaneous, conflicting file accesses */
     private fileLock;
     private readonly filePath;
+    /**
+     * @param filePath The path to the token file (optionally relative to the
+     *   current working directory)
+     */
     constructor(filePath: string);
     load(): Promise<string | undefined>;
     save(refresh_token: string): Promise<void>;

package/dist/Token/FileStorage.js

@@ -1,9 +1,24 @@
 import { Mutex } from 'async-mutex';
 import fs from 'node:fs';
 import path from 'node:path';
+/**
+ * Save a refresh token to a specific file
+ *
+ * Care _must_ be taken when using this persistence strategy that:
+ *
+ * 1. The token file is not publicly accessible
+ * 2. The token file is _not_ commited to a public repository
+ *
+ * This strategy is appropriate only in very limited set of use cases.
+ */
 export class FileStorage {
+    /** Prevent multiple simultaneous, conflicting file accesses */
     fileLock = new Mutex();
     filePath;
+    /**
+     * @param filePath The path to the token file (optionally relative to the
+     *   current working directory)
+     */
     constructor(filePath) {
         this.filePath = path.resolve(process.cwd(), filePath);
     }

package/dist/Token/Response.d.ts

@@ -1,2 +1,3 @@
 import * as OpenIDClient from 'openid-client';
+/** @see {@link https://github.com/panva/openid-client/blob/79386b7f120dc9bdc7606886a26e4ea7d011ee51/src/index.ts#L4268 `openid-client` grant request return type} */
 export type Response = OpenIDClient.TokenEndpointResponse & OpenIDClient.TokenEndpointResponseHelpers;

package/dist/Token/Storage.d.ts

@@ -1,4 +1,7 @@
+/** Persistent refresh token storage */
 export interface Storage {
+    /** Load the stored refresh token from persistent storage, if present */
     load(): Promise<string | undefined>;
+    /** Save a refresh token to persistent storage */
     save(refresh_token: string): Promise<void>;
 }

package/dist/Token/index.d.ts

@@ -1,3 +1,4 @@
 export * from './FileStorage.js';
 export * from './Response.js';
+export * as Scope from './Scope.js';
 export * from './Storage.js';

package/dist/Token/index.js

@@ -1,3 +1,4 @@
 export * from './FileStorage.js';
 export * from './Response.js';
+export * as Scope from './Scope.js';
 export * from './Storage.js';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export * from './Client.js';
 export * from './Credentials.js';
 export * from './Injection.js';
-export * as Scope from './Scope.js';
+export * as Localhost from './Localhost/index.js';
+export { Client as Options } from './Options.js';
 export * as Token from './Token/index.js';
-export * from './WebServer.js';

package/dist/index.js

@@ -1,6 +1,5 @@
 export * from './Client.js';
 export * from './Credentials.js';
 export * from './Injection.js';
-export * as Scope from './Scope.js';
+export * as Localhost from './Localhost/index.js';
 export * as Token from './Token/index.js';
-export * from './WebServer.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oauth2-cli",
-  "version": "0.8.8",
-  "description": "Acquire API access tokens via OAuth 2.0 within CLI tools",
+  "version": "1.0.0",
+  "description": "Acquire API access tokens via OAuth 2.0 / OpenID Connect within CLI tools",
   "homepage": "https://github.com/battis/oauth2-cli/tree/main/packages/oauth2-cli#readme",
   "repository": {
     "type": "git",
@@ -20,10 +20,11 @@
     "async-mutex": "^0.5.0",
     "express": "^5.2.1",
     "oauth4webapi": "^3.8.5",
+    "open": "^11.0.0",
     "openid-client": "^6.8.2",
     "ora": "^9.3.0",
-    "gcrtl": "0.1.7",
-    "requestish": "0.1.1"
+    "requestish": "0.1.3",
+    "gcrtl": "0.1.7"
   },
   "devDependencies": {
     "@battis/descriptive-types": "^0.2.6",

package/views/complete.ejs

@@ -10,37 +10,37 @@
       integrity="sha384-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH"
       crossorigin="anonymous"
     />
-    <style>
-      .wrapper {
-        display: grid;
-        grid-template-columns: 1fr auto 1fr;
-        grid-template-rows: 1fr auto 1.61803fr;
-        position: absolute;
-        width: 100vw;
-        height: 100vh;
-        top: 0;
-        left: 0;
-      }
-      .center {
-        grid-row: 2;
-        grid-column: 2;
-      }
-    </style>
   </head>
   <body>
-    <div class="wrapper">
-      <div class="center container">
-        <h1>
-          <%= name %>
-          Authorization Complete
-        </h1>
-        <p>You may close this window.</p>
+    <div
+      class="modal fade"
+      id="modal"
+      data-bs-backdrop="static"
+      data-bs-keyboard="false"
+      tabindex="-1"
+      aria-hidden="true"
+    >
+      <div class="modal-dialog">
+        <div class="modal-content">
+          <div class="modal-header">
+            <h1 class="modal-title fs-5"><%= name %> Authorization Complete</h1>
+          </div>
+          <div class="modal-body">
+            You have authorized access to <%= name %> for <%= reason %> using
+            your credentials.
+          </div>
+          <div class="modal-footer">You may close this window.</div>
+        </div>
       </div>
     </div>
+
     <script
       src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"
       integrity="sha384-YvpcrYf0tY3lHB60NNkmXc5s9fDVZLESaAA55NDzOxhy9GkcIdslK1eN7N6jIeHz"
       crossorigin="anonymous"
     ></script>
+    <script>
+      bootstrap.Modal.getOrCreateInstance('#modal').show();
+    </script>
   </body>
 </html>

package/views/error.ejs

@@ -10,34 +10,35 @@
       integrity="sha384-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH"
       crossorigin="anonymous"
     />
-    <style>
-      .wrapper {
-        display: grid;
-        grid-template-columns: 1fr auto 1fr;
-        grid-template-rows: 1fr auto 1.61803fr;
-        position: absolute;
-        width: 100vw;
-        height: 100vh;
-        top: 0;
-        left: 0;
-      }
-      .center {
-        grid-row: 2;
-        grid-column: 2;
-      }
-    </style>
   </head>
   <body>
-    <div class="wrapper">
-      <div class="center container">
-        <h1>
-          <%= name %>
-          Authorization Error
-        </h1>
-        <div class="alert alert-danger" role="alert">
-          <pre><%= JSON.stringify(error, null, 2) %></pre>
+    <div
+      class="modal fade"
+      id="modal"
+      data-bs-backdrop="static"
+      data-bs-keyboard="false"
+      tabindex="-1"
+      aria-hidden="true"
+    >
+      <div class="modal-dialog">
+        <div class="modal-content">
+          <div class="modal-header">
+            <h1 class="modal-title fs-5"><%= name %> Authorization Error</h1>
+          </div>
+          <div class="modal-body">
+            <p>
+              While authorizing access to
+              <%= name %>
+              for
+              <%= reason %>
+              an error was encountered:
+            </p>
+            <div class="alert alert-danger" role="alert">
+              <pre><%= JSON.stringify(error, null, 2) %></pre>
+            </div>
+          </div>
+          <div class="modal-footer">You may close this window.</div>
         </div>
-        <p>You may close this window.</p>
       </div>
     </div>
     <script
@@ -45,5 +46,8 @@
       integrity="sha384-YvpcrYf0tY3lHB60NNkmXc5s9fDVZLESaAA55NDzOxhy9GkcIdslK1eN7N6jIeHz"
       crossorigin="anonymous"
     ></script>
+    <script>
+      bootstrap.Modal.getOrCreateInstance('#modal').show();
+    </script>
   </body>
 </html>

package/dist/Session.d.ts

@@ -1,49 +0,0 @@
-import { PathString } from '@battis/descriptive-types';
-import { Request } from 'express';
-import { Client } from './Client.js';
-import { Injection } from './Injection.js';
-import * as Token from './Token/index.js';
-import * as WebServer from './WebServer.js';
-export type SessionOptions = {
-    client: Client;
-    /** See {@link WebServer.setViews Webserver.setViews()} */
-    views?: PathString;
-    /** Additional request injection for authorization code grant flow */
-    inject?: Injection;
-};
-export type SessionResolver = (response: Token.Response) => void | Promise<void>;
-export declare class Session {
-    readonly client: Client;
-    private readonly outOfBandRedirectServer;
-    /** PKCE code_verifier */
-    readonly code_verifier: string;
-    /** OAuth 2.0 state (if PKCE is not supported) */
-    readonly state: string;
-    /** Additional request injection for Authorization Code Grant request */
-    readonly inject?: Injection;
-    private spinner;
-    private _resolve?;
-    /**
-     * Method that resolves or rejects the promise returned from the
-     * {@link authorizationCodeGrant}
-     */
-    get resolve(): SessionResolver;
-    reject(cause: unknown): void;
-    constructor({ client, views, inject: request }: SessionOptions);
-    /** Instantiate the web server that will listen for the out-of-band redirect */
-    protected instantiateWebServer(options: Omit<WebServer.WebServerOptions, 'session'>): WebServer.WebServerInterface;
-    /**
-     * Trigger the start of the Authorization Code Grant flow, returnig a Promise
-     * that will resolve into the eventual token. This will close the out-of-band
-     * redirect server that creating the session started.
-     */
-    authorizationCodeGrant(): Promise<Token.Response>;
-    /** OAuth 2.0 redirect_uri that this session is handling */
-    get redirect_uri(): import("requestish/dist/URL.js").ish;
-    getAuthorizationUrl(): Promise<string>;
-    /**
-     * Express RequestHandler for the out-of-band redirect in the Authorization
-     * Code Grant flow
-     */
-    handleAuthorizationCodeRedirect(req: Request): Promise<void>;
-}

package/dist/Session.js

@@ -1,111 +0,0 @@
-import { Colors } from '@qui-cli/colors';
-import * as gcrtl from 'gcrtl';
-import * as OpenIDClient from 'openid-client';
-import ora from 'ora';
-import * as WebServer from './WebServer.js';
-export class Session {
-    client;
-    outOfBandRedirectServer;
-    /** PKCE code_verifier */
-    code_verifier = OpenIDClient.randomPKCECodeVerifier();
-    /** OAuth 2.0 state (if PKCE is not supported) */
-    state = OpenIDClient.randomState();
-    /** Additional request injection for Authorization Code Grant request */
-    inject;
-    spinner;
-    _resolve;
-    /**
-     * Method that resolves or rejects the promise returned from the
-     * {@link authorizationCodeGrant}
-     */
-    get resolve() {
-        if (!this._resolve) {
-            throw new Error(`${this.client.clientName()}'s Session resolve method is ${this._resolve}`);
-        }
-        return this._resolve;
-    }
-    reject(cause) {
-        throw new Error(`${this.client.clientName()}'s Session failed`, { cause });
-    }
-    constructor({ client, views, inject: request }) {
-        this.client = client;
-        this.spinner = ora(`${this.client.clientName()} awaiting interactive authorization`).start();
-        this.inject = request;
-        this.outOfBandRedirectServer = this.instantiateWebServer({ views });
-    }
-    /** Instantiate the web server that will listen for the out-of-band redirect */
-    instantiateWebServer(options) {
-        return new WebServer.WebServer({ session: this, ...options });
-    }
-    /**
-     * Trigger the start of the Authorization Code Grant flow, returnig a Promise
-     * that will resolve into the eventual token. This will close the out-of-band
-     * redirect server that creating the session started.
-     */
-    async authorizationCodeGrant() {
-        return await new Promise((resolve, reject) => {
-            try {
-                this._resolve = (response) => {
-                    let closed = false;
-                    this.spinner.text = `${this.client.clientName()} waiting for out-of-band redirect server to shut down`;
-                    this.outOfBandRedirectServer.close().then(() => {
-                        closed = true;
-                        this.spinner.succeed(`Interactive authorization for ${this.client.clientName()} complete`);
-                        resolve(response);
-                    });
-                    setTimeout(() => {
-                        if (!closed) {
-                            this.spinner.text =
-                                `Still waiting for out-of-band redirect server for ${this.client.clientName()} to shut down.\n` +
-                                    '  Your browser may be holding the connection to the server open.\n\n' +
-                                    '  Please close the "Authorization Complete" tab in your browser.';
-                        }
-                    }, 5000);
-                    setTimeout(() => {
-                        if (!closed) {
-                            this.spinner.text =
-                                `Still waiting for out-of-band redirect server for ${this.client.clientName()} to shut down.\n` +
-                                    '  Your browser may be holding the connection to the server open.\n\n' +
-                                    '  Please close the browser window.';
-                        }
-                    }, 10000);
-                    setTimeout(() => {
-                        if (!closed) {
-                            this.spinner.text =
-                                `Still waiting for out-of-band redirect server for ${this.client.clientName()} to shut down.\n` +
-                                    '  Your browser may be holding the connection to the server open.\n\n' +
-                                    '  Please quit the browser.';
-                        }
-                    }, 15000);
-                };
-                const url = gcrtl
-                    .expand(this.outOfBandRedirectServer.authorization_endpoint, this.client.redirect_uri)
-                    .toString();
-                //open(url);
-                this.spinner.text = `Please continue interactive authorization for ${this.client.clientName()} at ${Colors.url(url)} in your browser`;
-            }
-            catch (cause) {
-                this.spinner.text = `Waiting for out-of-band redirect server for ${this.client.clientName()} to shut down`;
-                this.outOfBandRedirectServer.close().then(() => {
-                    this.spinner.fail(`Interactive authorization for ${this.client.clientName()} failed`);
-                    reject(new Error(`Error in Authorization Code flow for ${this.client.clientName()}`, { cause }));
-                });
-            }
-        });
-    }
-    /** OAuth 2.0 redirect_uri that this session is handling */
-    get redirect_uri() {
-        return this.client.redirect_uri;
-    }
-    async getAuthorizationUrl() {
-        return (await this.client.getAuthorizationUrl(this)).toString();
-    }
-    /**
-     * Express RequestHandler for the out-of-band redirect in the Authorization
-     * Code Grant flow
-     */
-    async handleAuthorizationCodeRedirect(req) {
-        this.spinner.text = `Completing access token request fro ${this.client.clientName()} with provided authorization code`;
-        return await this.client.handleAuthorizationCodeRedirect(req, this);
-    }
-}

package/dist/Token/addHelpers.d.ts

@@ -1,8 +0,0 @@
-/**
- * Reaching into the bowels of openid-client to be able to fully de-serialize a
- * serialized token response
- */
-import * as oauth from 'oauth4webapi';
-import { TokenEndpointResponseHelpers } from 'openid-client';
-/** @see https://github.com/panva/openid-client/blob/79386b7f120dc9bdc7606886a26e4ea7d011ee51/src/index.ts#L2018-L2022 */
-export declare function addHelpers(response: oauth.TokenEndpointResponse): asserts response is typeof response & TokenEndpointResponseHelpers;