@oauth2-cli/qui-cli 0.7.15 → 1.0.0

package/dist/OAuth2Plugin.js

@@ -3,12 +3,13 @@ import { Env } from '@qui-cli/env';
 import { Log } from '@qui-cli/log';
 import * as Plugin from '@qui-cli/plugin';
 import * as OAuth2CLI from 'oauth2-cli';
-import * as requestish from 'requestish';
+import { URL } from 'requestish';
 export class OAuth2Plugin {
     name;
     static names = [];
     static registeredPorts = {};
     overrideName;
+    reason;
     /**
      * @param name Human-readable name for client in messages. Must also be a
      *   unique qui-cli plugin name.
@@ -19,15 +20,21 @@ export class OAuth2Plugin {
             throw new Error(`A @qui-cli/plugin named ${Colors.value(name)} has already been instantiated.`);
         }
     }
+    /** Configured client credentials */
     credentials;
+    /** Configured client base_url */
     base_url;
+    /** Configured usage information */
     man = {
         heading: 'OAuth 2.0 / Open ID Connect client options'
     };
+    /** Configured reference URLs for credentials */
     url = undefined;
+    /** Configured hint values for credentials */
     hint = {
         redirect_uri: Colors.quotedValue(`"http://localhost:3000/redirect"`)
     };
+    /** Configured environment variable names for credentials */
     env = {
         issuer: 'ISSUER',
         client_id: 'CLIENT_ID',
@@ -38,13 +45,76 @@ export class OAuth2Plugin {
         base_url: 'BASE_URL',
         scope: 'SCOPE'
     };
+    /** Configured credentials to suppress in usage and init */
     suppress = {
         scope: true
     };
+    /** Configured request components for client to inject */
     inject = undefined;
-    views = undefined;
+    /** Configured {@link OAuth2CLI.Localhost.Options} to pass to client */
+    localhost;
+    /** Configured client refresh token storage strategy */
     storage = undefined;
     _client = undefined;
+    /**
+     * Configured oauth2-cli client
+     *
+     * Do _not_ access until intitialization is complete -- the client will be
+     * configured upon first access based on available configuration known at that
+     * time
+     */
+    get client() {
+        if (!this._client) {
+            if (!this.credentials?.client_id) {
+                throw new Error(`A ${Colors.varName(this.env.client_id)} ${Colors.keyword('must')} ` +
+                    `be configured for ${this.overrideName || this.name}.`);
+            }
+            if (!this.credentials?.client_secret) {
+                throw new Error(`A ${Colors.varName(this.env.client_secret)} ${Colors.keyword('must')} ` +
+                    `be configured for ${this.overrideName || this.name}.`);
+            }
+            if (!this.credentials?.redirect_uri) {
+                throw new Error(`A ${Colors.varName(this.env.redirect_uri)} ${Colors.keyword('must')} ` +
+                    `be configured for ${this.overrideName || this.name}.`);
+            }
+            if (!this.credentials?.issuer) {
+                if (!this.credentials?.authorization_endpoint) {
+                    throw new Error(`Either an ${Colors.varName(this.env.issuer)} or ` +
+                        `${Colors.varName(this.env.authorization_endpoint)} ` +
+                        `${Colors.keyword('must')} be configured for ` +
+                        `${this.overrideName || this.name}.`);
+                }
+                if (!this.credentials?.token_endpoint) {
+                    throw new Error(`Either an ${Colors.varName(this.env.issuer)} or ` +
+                        `${Colors.varName(this.env.token_endpoint)} ` +
+                        `${Colors.keyword('must')} be configured for ` +
+                        `${this.overrideName || this.name}.`);
+                }
+            }
+            this._client = this.instantiateClient({
+                name: this.overrideName || this.name,
+                reason: this.reason,
+                credentials: this.credentials,
+                base_url: this.base_url,
+                inject: this.inject,
+                localhost: this.localhost,
+                storage: this.storage
+            });
+        }
+        return this._client;
+    }
+    /**
+     * Configure plugin for use
+     *
+     * May be called repeatedly, overlaying different options as they become
+     * available
+     *
+     * Invoked automatically by
+     * {@link https://github.com/battis/qui-cli#readme qui-cli} during
+     * initialization
+     *
+     * @see {@link Configuration}
+     */
     configure(proposal = {}) {
         function hydrate(p, c) {
             if (p) {
@@ -60,6 +130,7 @@ export class OAuth2Plugin {
             return c;
         }
         this.overrideName = Plugin.hydrate(proposal.name, this.overrideName);
+        this.reason = Plugin.hydrate(proposal.reason, this.reason);
         this.credentials = hydrate(proposal.credentials, this.credentials);
         this.base_url = Plugin.hydrate(proposal.base_url, this.base_url);
         this.storage = Plugin.hydrate(proposal.storage, this.storage);
@@ -69,8 +140,9 @@ export class OAuth2Plugin {
         this.hint = hydrate(proposal.hint, this.hint);
         this.env = hydrate(proposal.env, this.env);
         this.suppress = hydrate(proposal.suppress, this.suppress);
+        this.localhost = hydrate(proposal.localhost, this.localhost);
         if (this.credentials?.redirect_uri) {
-            const url = requestish.URL.from(this.credentials.redirect_uri);
+            const url = URL.from(this.credentials.redirect_uri);
             if (url.hostname !== 'localhost' &&
                 !/^\/https?\/localhost(:\d+)?\//.test(url.pathname)) {
                 Log.warning(`The ${Colors.varName(this.env.redirect_uri)} value ${Colors.url(this.credentials.redirect_uri)} for ${this.overrideName || this.name} may not work: it ` +
@@ -93,6 +165,15 @@ export class OAuth2Plugin {
             }
         }
     }
+    /**
+     * Provide usage options to
+     * {@link https://github.com/battis/qui-cli#readme qui-cli} for display to user
+     * on command line
+     *
+     * Invoked automatically by
+     * {@link https://github.com/battis/qui-cli#readme qui-cli} during
+     * initialization
+     */
     options() {
         const descriptions = {
             issuer: `The OpenID ${Colors.keyword('issuer')} URL is set from the ` +
@@ -140,6 +221,13 @@ export class OAuth2Plugin {
             ]
         };
     }
+    /**
+     * Intialize plugin configuration from command line options and environment
+     *
+     * Invoked automatically by
+     * {@link https://github.com/battis/qui-cli#readme qui-cli} during
+     * initialization
+     */
     async init(_) {
         const credentials = {};
         const base_url = this.base_url ||
@@ -157,57 +245,43 @@ export class OAuth2Plugin {
         }
         this.configure({ credentials, base_url });
     }
+    /**
+     * Instantiate the `oauth2-cli` client
+     *
+     * Available hook for custom configurations in plugin development
+     */
     instantiateClient(options) {
         return new OAuth2CLI.Client(options);
     }
-    get client() {
-        if (!this._client) {
-            if (!this.credentials?.client_id) {
-                throw new Error(`A ${Colors.varName(this.env.client_id)} ${Colors.keyword('must')} ` +
-                    `be configured for ${this.overrideName || this.name}.`);
-            }
-            if (!this.credentials?.client_secret) {
-                throw new Error(`A ${Colors.varName(this.env.client_secret)} ${Colors.keyword('must')} ` +
-                    `be configured for ${this.overrideName || this.name}.`);
-            }
-            if (!this.credentials?.redirect_uri) {
-                throw new Error(`A ${Colors.varName(this.env.redirect_uri)} ${Colors.keyword('must')} ` +
-                    `be configured for ${this.overrideName || this.name}.`);
-            }
-            if (!this.credentials?.issuer) {
-                if (!this.credentials?.authorization_endpoint) {
-                    throw new Error(`Either an ${Colors.varName(this.env.issuer)} or ` +
-                        `${Colors.varName(this.env.authorization_endpoint)} ` +
-                        `${Colors.keyword('must')} be configured for ` +
-                        `${this.overrideName || this.name}.`);
-                }
-                if (!this.credentials?.token_endpoint) {
-                    throw new Error(`Either an ${Colors.varName(this.env.issuer)} or ` +
-                        `${Colors.varName(this.env.token_endpoint)} ` +
-                        `${Colors.keyword('must')} be configured for ` +
-                        `${this.overrideName || this.name}.`);
-                }
-            }
-            this._client = this.instantiateClient({
-                name: this.overrideName || this.name,
-                credentials: this.credentials,
-                base_url: this.base_url,
-                inject: this.inject,
-                views: this.views,
-                storage: this.storage
-            });
-        }
-        return this._client;
-    }
+    /**
+     * Convenience method
+     *
+     * @see {@link OAuth2CLI.Client.request}
+     */
     request(...args) {
         return this.client.request(...args);
     }
+    /**
+     * Convenience method
+     *
+     * @see {@link OAuth2CLI.Client.requestJSON}
+     */
     requestJSON(...args) {
         return this.client.requestJSON(...args);
     }
+    /**
+     * Convenience method
+     *
+     * @see {@link OAuth2CLI.Client.fetch}
+     */
     fetch(...args) {
         return this.client.fetch(...args);
     }
+    /**
+     * Convenience method
+     *
+     * @see {@link OAuth2CLI.Client.fetchJSON}
+     */
     fetchJSON(...args) {
         return this.client.fetchJSON(...args);
     }

package/dist/Token/EnvironmentStorage.d.ts

@@ -1,6 +1,20 @@
 import { Token } from 'oauth2-cli';
+/**
+ * Persist a refresh token in the local environment
+ *
+ * Care should be taken when using this persistence strategy to:
+ *
+ * 1. Ideally encrypt or otherwise secure the environment value (see
+ *    {@link https://github.com/battis/oauth2-cli/tree/main/examples/qui-cli/04%201password-integration#readme 1password-integration}
+ *    example for one approach)
+ * 2. Do not commit `.env` files to a public repo
+ */
 export declare class EnvironmentStorage implements Token.Storage {
     private tokenEnvVar;
+    /**
+     * @param tokenEnvVar Name of the environment variable containing the refresh
+     *   token, defaults to `REFRESH_TOKEN`
+     */
     constructor(tokenEnvVar?: string);
     load(): Promise<string | undefined>;
     save(refresh_token: string): Promise<void>;

package/dist/Token/EnvironmentStorage.js

@@ -1,6 +1,20 @@
 import { Env } from '@qui-cli/env';
+/**
+ * Persist a refresh token in the local environment
+ *
+ * Care should be taken when using this persistence strategy to:
+ *
+ * 1. Ideally encrypt or otherwise secure the environment value (see
+ *    {@link https://github.com/battis/oauth2-cli/tree/main/examples/qui-cli/04%201password-integration#readme 1password-integration}
+ *    example for one approach)
+ * 2. Do not commit `.env` files to a public repo
+ */
 export class EnvironmentStorage {
     tokenEnvVar;
+    /**
+     * @param tokenEnvVar Name of the environment variable containing the refresh
+     *   token, defaults to `REFRESH_TOKEN`
+     */
     constructor(tokenEnvVar = 'REFRESH_TOKEN') {
         this.tokenEnvVar = tokenEnvVar;
     }

package/dist/{Unregistered.d.ts → extendable.d.ts}

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

package/dist/{Unregistered.js → extendable.js}

@@ -1,4 +1,4 @@
-export { Scope, WebServer } from 'oauth2-cli';
+export { Localhost } from 'oauth2-cli';
 export * from './Client.js';
 export * from './OAuth2Plugin.js';
 export * as Token from './Token/index.js';

package/dist/index.d.ts

@@ -1,2 +1,2 @@
+export * from './extendable.js';
 export * as OAuth2 from './OAuth2.js';
-export * from './Unregistered.js';

package/dist/index.js

@@ -1,2 +1,2 @@
+export * from './extendable.js';
 export * as OAuth2 from './OAuth2.js';
-export * from './Unregistered.js';

package/extendable/Client.d.ts

@@ -0,0 +1,24 @@
+import { JSONValue } from '@battis/typescript-tricks';
+import { Request } from 'express';
+import * as OAuth2CLI from 'oauth2-cli';
+import type * as OpenIDClient from 'openid-client';
+import * as requestish from 'requestish';
+/**
+ * Wrap {@link https://www.npmjs.com/package/openid-client openid-client} in a
+ * class instance specific to a particular OAuth/OpenID server credential-set,
+ * abstracting away most flows into {@link getToken}
+ *
+ * Emits {@link Client.TokenEvent} whenever a new access token is received
+ *
+ * Provides optional debug logging output using
+ * {@link https://www.npmjs.com/package/@qui-cli/env @qui-cli/env}
+ */
+export declare class Client<C extends OAuth2CLI.Credentials = OAuth2CLI.Credentials> extends OAuth2CLI.Client<C> {
+    getConfiguration(): Promise<OpenIDClient.Configuration>;
+    authorize(): Promise<OAuth2CLI.Token.Response>;
+    handleAuthorizationCodeRedirect(request: Request, session: OAuth2CLI.Localhost.Server): Promise<OAuth2CLI.Token.Response>;
+    protected refreshTokenGrant(token: OAuth2CLI.Token.Response): Promise<OAuth2CLI.Token.Response | undefined>;
+    protected save(response: OAuth2CLI.Token.Response): Promise<OAuth2CLI.Token.Response>;
+    request(url: requestish.URL.ish, method?: string, body?: OpenIDClient.FetchBody, headers?: requestish.Headers.ish, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<Response>;
+    requestJSON<J extends JSONValue = JSONValue>(url: requestish.URL.ish, method?: string, body?: OpenIDClient.FetchBody, headers?: requestish.Headers.ish, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<J>;
+}

package/extendable/Client.js

@@ -0,0 +1,71 @@
+import { Log } from '@qui-cli/log';
+import * as OAuth2CLI from 'oauth2-cli';
+/**
+ * Wrap {@link https://www.npmjs.com/package/openid-client openid-client} in a
+ * class instance specific to a particular OAuth/OpenID server credential-set,
+ * abstracting away most flows into {@link getToken}
+ *
+ * Emits {@link Client.TokenEvent} whenever a new access token is received
+ *
+ * Provides optional debug logging output using
+ * {@link https://www.npmjs.com/package/@qui-cli/env @qui-cli/env}
+ */
+export class Client extends OAuth2CLI.Client {
+    async getConfiguration() {
+        const creating = !this.config;
+        const config = await super.getConfiguration();
+        if (creating) {
+            Log.debug(`${this.name} OAuth 2.0 configuration created`, {
+                credentials: this.credentials,
+                config: {
+                    serverMetadata: config.serverMetadata(),
+                    clientMetadata: config.clientMetadata()
+                }
+            });
+        }
+        return config;
+    }
+    async authorize() {
+        Log.debug(`Authorizing ${this.name} new access token`);
+        const response = await super.authorize();
+        Log.debug(`Authorized ${this.name} new access token`, { response });
+        return response;
+    }
+    async handleAuthorizationCodeRedirect(request, session) {
+        Log.debug(`Handling ${this.name} authorization code redirect`, { request });
+        const response = await super.handleAuthorizationCodeRedirect(request, session);
+        Log.debug(`Received ${this.name} authorization code response`, {
+            response
+        });
+        return response;
+    }
+    async refreshTokenGrant(token) {
+        Log.debug(`Refreshing expired ${this.name} access token`, {
+            token
+        });
+        const refreshed = await super.refreshTokenGrant(token);
+        Log.debug(`Received refreshed ${this.name} access token`, {
+            token: refreshed
+        });
+        return refreshed;
+    }
+    async save(response) {
+        Log.debug(`Persisting ${this.name} refresh token, if present and storage configured`, {
+            response
+        });
+        return await super.save(response);
+    }
+    async request(url, method, body, headers, dPoPOptions) {
+        Log.debug(`Sending request to ${this.name}`, {
+            request: { method, url, headers, body, dPoPOptions }
+        });
+        const response = await super.request(url, method, body, headers, dPoPOptions);
+        Log.debug(`Received response from ${this.name}`, { response });
+        return response;
+    }
+    async requestJSON(url, method, body, headers, dPoPOptions) {
+        const json = await super.requestJSON(url, method, body, headers, dPoPOptions);
+        Log.debug(`Parsed JSON from ${this.name} response`, { json });
+        return json;
+    }
+}

package/extendable/OAuth2Plugin.d.ts

@@ -0,0 +1,154 @@
+import { URLString } from '@battis/descriptive-types';
+import { JSONValue } from '@battis/typescript-tricks';
+import * as Plugin from '@qui-cli/plugin';
+import * as OAuth2CLI from 'oauth2-cli';
+import { URL } from 'requestish';
+import { Client } from './Client.js';
+/** Key for value to be read from the local environment */
+type EnvironmentKey = 'issuer' | 'client_id' | 'client_secret' | 'redirect_uri' | 'authorization_endpoint' | 'token_endpoint' | 'scope' | 'base_url';
+/** Names of environment variables */
+type EnvironmentVars = Record<EnvironmentKey, string>;
+/** Reference URLs for environment variables */
+type SupportUrls = Record<EnvironmentKey, URLString>;
+/** Hint values for environment variables */
+type Hints = Record<EnvironmentKey, string>;
+/** Environment variables to ignore and supporess in usage documentation */
+type EnvVarSuppression = Record<EnvironmentKey, boolean>;
+/** Custom usage information to present to user */
+type Usage = {
+    heading: string;
+    text?: string[];
+};
+/** Plugin configuration */
+export type Configuration<C extends OAuth2CLI.Credentials = OAuth2CLI.Credentials> = Plugin.Configuration & {
+    /** Human-readable name for client in messages (e.g. the name of the API) */
+    name?: string;
+    /**
+     * Human-readable for authorizing access in messages (e.g. the name of the
+     * app)
+     */
+    reason?: string;
+    /** OAuth 2.0/OpenID Connect credential set */
+    credentials?: Partial<C>;
+    /** Base URL for all non-absolute requests */
+    base_url?: URL.ish;
+    /** Request components to inject into server requests */
+    inject?: OAuth2CLI.Injection;
+    /** Refresh token storage service */
+    storage?: OAuth2CLI.Token.Storage;
+    /** CLI usage section header and text */
+    man?: Usage;
+    /** Reference URLs for particular credential values */
+    url?: Partial<SupportUrls>;
+    /** Hint values for particular credential values */
+    hint?: Partial<Hints>;
+    /** Actual environment variable names for each credential value */
+    env?: Partial<EnvironmentVars>;
+    /** Should a particular credential value _not_ be loaded from the environment? */
+    suppress?: Partial<EnvVarSuppression>;
+    localhost?: OAuth2CLI.Options['localhost'];
+};
+export declare class OAuth2Plugin<C extends OAuth2CLI.Credentials = OAuth2CLI.Credentials, L extends Client<C> = Client<C>> {
+    readonly name: string;
+    [key: string]: unknown;
+    private static names;
+    private static registeredPorts;
+    private overrideName?;
+    private reason?;
+    /**
+     * @param name Human-readable name for client in messages. Must also be a
+     *   unique qui-cli plugin name.
+     */
+    constructor(name?: string);
+    /** Configured client credentials */
+    private credentials?;
+    /** Configured client base_url */
+    private base_url?;
+    /** Configured usage information */
+    private man;
+    /** Configured reference URLs for credentials */
+    private url?;
+    /** Configured hint values for credentials */
+    private hint;
+    /** Configured environment variable names for credentials */
+    private env;
+    /** Configured credentials to suppress in usage and init */
+    private suppress?;
+    /** Configured request components for client to inject */
+    private inject?;
+    /** Configured {@link OAuth2CLI.Localhost.Options} to pass to client */
+    private localhost?;
+    /** Configured client refresh token storage strategy */
+    private storage?;
+    private _client?;
+    /**
+     * Configured oauth2-cli client
+     *
+     * Do _not_ access until intitialization is complete -- the client will be
+     * configured upon first access based on available configuration known at that
+     * time
+     */
+    get client(): L;
+    /**
+     * Configure plugin for use
+     *
+     * May be called repeatedly, overlaying different options as they become
+     * available
+     *
+     * Invoked automatically by
+     * {@link https://github.com/battis/qui-cli#readme qui-cli} during
+     * initialization
+     *
+     * @see {@link Configuration}
+     */
+    configure(proposal?: Configuration<C>): void;
+    /**
+     * Provide usage options to
+     * {@link https://github.com/battis/qui-cli#readme qui-cli} for display to user
+     * on command line
+     *
+     * Invoked automatically by
+     * {@link https://github.com/battis/qui-cli#readme qui-cli} during
+     * initialization
+     */
+    options(): Plugin.Options;
+    /**
+     * Intialize plugin configuration from command line options and environment
+     *
+     * Invoked automatically by
+     * {@link https://github.com/battis/qui-cli#readme qui-cli} during
+     * initialization
+     */
+    init(_: Plugin.ExpectedArguments<typeof this.options>): Promise<void>;
+    /**
+     * Instantiate the `oauth2-cli` client
+     *
+     * Available hook for custom configurations in plugin development
+     */
+    protected instantiateClient(options: OAuth2CLI.Options<C>): L;
+    /**
+     * Convenience method
+     *
+     * @see {@link OAuth2CLI.Client.request}
+     */
+    request(...args: Parameters<OAuth2CLI.Client<C>['request']>): Promise<Response>;
+    /**
+     * Convenience method
+     *
+     * @see {@link OAuth2CLI.Client.requestJSON}
+     */
+    requestJSON<T extends JSONValue>(...args: Parameters<OAuth2CLI.Client<C>['requestJSON']>): Promise<T>;
+    /**
+     * Convenience method
+     *
+     * @see {@link OAuth2CLI.Client.fetch}
+     */
+    fetch(...args: Parameters<OAuth2CLI.Client<C>['fetch']>): Promise<Response>;
+    /**
+     * Convenience method
+     *
+     * @see {@link OAuth2CLI.Client.fetchJSON}
+     */
+    fetchJSON<T extends JSONValue>(...args: Parameters<OAuth2CLI.Client<C>['fetchJSON']>): Promise<T>;
+}
+export {};