@oauth2-cli/qui-cli 0.7.16 → 1.0.0

package/extendable/OAuth2Plugin.js

@@ -0,0 +1,288 @@
+import { Colors } from '@qui-cli/colors';
+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 { 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.
+     */
+    constructor(name = '@oauth2-cli/qui-cli') {
+        this.name = name;
+        if (OAuth2Plugin.names.includes(name)) {
+            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',
+        client_secret: 'CLIENT_SECRET',
+        redirect_uri: 'REDIRECT_URI',
+        authorization_endpoint: 'AUTHORIZATION_ENDPOINT',
+        token_endpoint: 'TOKEN_ENDPOINT',
+        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;
+    /** 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) {
+                for (const k of Object.keys(p)) {
+                    if (p[k] !== undefined) {
+                        if (!c) {
+                            c = {};
+                        }
+                        c[k] = p[k];
+                    }
+                }
+            }
+            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);
+        this.inject = hydrate(proposal.inject, this.inject);
+        this.man = Plugin.hydrate(proposal.man, this.man);
+        this.url = hydrate(proposal.url, this.url);
+        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 = 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 ` +
+                    `${Colors.keyword('must')} redirect to ${Colors.url('localhost')}`);
+            }
+            if (url.protocol !== 'http:' &&
+                !/^\/http\/localhost(:\d+)?\//.test(url.pathname)) {
+                Log.warning(`The ${Colors.url(url.protocol)} protocol may not work without additional configuration. The out-` +
+                    `of-band server listening for the ` +
+                    `${this.overrideName || this.name} redirect is not automatically ` +
+                    `provisioned with an SSL certificate`);
+            }
+            if (OAuth2Plugin.registeredPorts[url.port] &&
+                OAuth2Plugin.registeredPorts[url.port] !== this.name) {
+                Log.warning(`The port ${Colors.value(url.port)} has already been registered to another instance of this plugin ` +
+                    `named ${Colors.value(OAuth2Plugin.registeredPorts[url.port])}. This will likely cause a failure if both ` +
+                    `${this.overrideName || this.name} and ` +
+                    `${OAuth2Plugin.registeredPorts[url.port]} are listening for ` +
+                    `redirects at relatively proximate moments in time.`);
+            }
+        }
+    }
+    /**
+     * 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 ` +
+                `environment variable ${Colors.varName(this.env.issuer)}, if present. ` +
+                `The ${Colors.varName(this.env.issuer)} is also used as a base URL for ` +
+                `any relative URL in API requests, unless ` +
+                `${Colors.varName(this.env.base_url)} is defined.`,
+            client_id: `The OAuth 2.0 ${Colors.keyword('client_id')} is set from the ` +
+                `environment variable ${Colors.varName(this.env.client_id)}, if ` +
+                `present.`,
+            client_secret: `The OAuth 2.0 ${Colors.keyword('client_secret')} is set from the ` +
+                `environment variable ${Colors.varName(this.env.client_secret)}, if ` +
+                `present.`,
+            scope: `The OAuth 2.0 ${Colors.keyword('scope')} is set from the environment ` +
+                `variable ${Colors.varName(this.env.scope)}, if present.`,
+            redirect_uri: `The OAuth 2.0 ${Colors.keyword('redirect_uri')}, which must at least ` +
+                `redirect to ${Colors.url('localhost')}, is set from the environment ` +
+                `variable ${Colors.varName(this.env.redirect_uri)}, if present.`,
+            authorization_endpoint: `The OAuth 2.0 ${Colors.keyword('authorization_endpoint')} is set ` +
+                `from the environment variable ` +
+                `${Colors.varName(this.env.authorization_endpoint)}, if present.`,
+            token_endpoint: `The OAuth 2.0 ${Colors.keyword('token_endpoint')} is set from the ` +
+                `environment variable ${Colors.varName(this.env.token_endpoint)}, if ` +
+                `present and will fall back to ` +
+                `${Colors.varName(this.env.authorization_endpoint)} if not provided.`,
+            base_url: `The base URL to use for API requests is set from the ` +
+                `environment variable ${Colors.varName(this.env.base_url)}, if ` +
+                `present. If ${Colors.varName(this.env.base_url)} is not defined, ` +
+                `${Colors.varName(this.env.issuer)} will be used as a base URL for ` +
+                `relative URL requests.`
+        };
+        return {
+            man: [
+                { level: 1, text: this.man.heading },
+                ...Object.keys(descriptions)
+                    .filter((key) => !this.suppress || !this.suppress[key])
+                    .map((key) => ({
+                    text: descriptions[key] +
+                        (this.hint[key] ? ` (e.g. ${this.hint[key]})` : '') +
+                        (this.url && this.url[key]
+                            ? ` See ${Colors.url(this.url[key])} for more information.`
+                            : '')
+                })),
+                ...(this.man.text || []).map((t) => ({ text: t }))
+            ]
+        };
+    }
+    /**
+     * 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 ||
+            (await Env.get({
+                key: this.env.base_url
+            }));
+        for (const key of Object.keys(this.env)) {
+            if (key !== 'base_url') {
+                // FIXME better typing
+                // @ts-expect-error 2322
+                credentials[key] =
+                    (this.credentials ? this.credentials[key] : undefined) ||
+                        (await Env.get({ key: this.env[key] }));
+            }
+        }
+        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);
+    }
+    /**
+     * 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/extendable/Token/EnvironmentStorage.d.ts

@@ -0,0 +1,21 @@
+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/extendable/Token/EnvironmentStorage.js

@@ -0,0 +1,27 @@
+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;
+    }
+    async load() {
+        return await Env.get({ key: this.tokenEnvVar });
+    }
+    async save(refresh_token) {
+        await Env.set({ key: this.tokenEnvVar, value: refresh_token });
+    }
+}

package/extendable/Token/index.d.ts

@@ -0,0 +1,2 @@
+export * from 'oauth2-cli/dist/Token/index.js';
+export * from './EnvironmentStorage.js';

package/extendable/Token/index.js

@@ -0,0 +1,2 @@
+export * from 'oauth2-cli/dist/Token/index.js';
+export * from './EnvironmentStorage.js';

package/extendable/extendable.d.ts

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

package/extendable/extendable.js

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

package/extendable/index.d.ts

@@ -0,0 +1 @@
+export * from "./extendable.js";

package/extendable/index.js

@@ -0,0 +1 @@
+export * from './extendable.js';

package/extendable/package.json

@@ -0,0 +1,5 @@
+{
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts"
+}

package/package.extendable.json

@@ -0,0 +1,5 @@
+{
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oauth2-cli/qui-cli",
-  "version": "0.7.16",
+  "version": "1.0.0",
   "description": "@qui-cli/plugin wrapper for oauth2-cli",
   "homepage": "https://github.com/battis/oauth2-cli/tree/main/packages/qui-cli#readme",
   "repository": {
@@ -17,8 +17,8 @@
   "types": "./dist/index.d.ts",
   "dependencies": {
     "@qui-cli/colors": "^3.2.3",
-    "requestish": "0.1.1",
-    "oauth2-cli": "0.8.9"
+    "oauth2-cli": "1.0.0",
+    "requestish": "0.1.3"
   },
   "devDependencies": {
     "@battis/descriptive-types": "^0.2.6",
@@ -28,6 +28,7 @@
     "@qui-cli/plugin": "^4.1.0",
     "@tsconfig/node24": "^24.0.4",
     "commit-and-tag-version": "^12.6.1",
+    "cpy-cli": "^7.0.0",
     "del-cli": "^7.0.0",
     "npm-run-all": "^4.1.5",
     "openid-client": "^6.8.2",
@@ -39,10 +40,14 @@
     "@qui-cli/plugin": ">=3"
   },
   "scripts": {
-    "clean": "del ./dist",
-    "build": "run-s build:*",
+    "clean": "run-s clean:*",
+    "clean:dist": "del ./dist",
+    "clean:extendable": "del ./extendable",
+    "build": "run-s build:**",
     "build:clean": "run-s clean",
-    "build:compile": "tsc",
+    "build:dist": "tsc",
+    "build:extendable:compile": "tsc --project tsconfig.extendable.json",
+    "build:extendable:package": "cpy ./package.extendable.json ./extendable/package.json",
     "release": "commit-and-tag-version"
   }
 }

package/tsconfig.extendable.json

@@ -0,0 +1,10 @@
+{
+  "extends": "@tsconfig/node24/tsconfig.json",
+  "compilerOptions": {
+    "allowJs": true,
+    "declaration": true,
+    "outDir": "./extendable"
+  },
+  "include": ["./src"],
+  "exclude": ["./src/index.ts", "./src/OAuth2.ts"]
+}