oauth2-cli 0.8.8 → 1.0.0

package/dist/Client.js

@@ -1,15 +1,11 @@
 import { Mutex } from 'async-mutex';
+import * as gcrtl from 'gcrtl';
 import { EventEmitter } from 'node:events';
 import path from 'node:path';
 import * as OpenIDClient from 'openid-client';
-import * as requestish from 'requestish';
-import * as Scope from './Scope.js';
-import { Session } from './Session.js';
-/**
- * A generic `redirect_uri` to use if the server does not require pre-registered
- * `redirect_uri` values
- */
-export const DEFAULT_REDIRECT_URI = 'http://localhost:3000/oauth2-cli/redirect';
+import { Body, Headers, URL, URLSearchParams } from 'requestish';
+import * as Localhost from './Localhost/index.js';
+import * as Token from './Token/index.js';
 /**
  * Wrap {@link https://www.npmjs.com/package/openid-client openid-client} in a
  * class instance specific to a particular OAuth/OpenID server credential-set,
@@ -19,86 +15,98 @@ export const DEFAULT_REDIRECT_URI = 'http://localhost:3000/oauth2-cli/redirect';
  */
 export class Client extends EventEmitter {
     static TokenEvent = 'token';
-    name;
+    _name;
+    /** Human-readable name for client in messages */
+    get name() {
+        if (this._name && this._name.length > 0) {
+            return this._name;
+        }
+        return 'API';
+    }
+    /** Human-readable reason for authorization in messages */
+    reason;
+    /** Credentials for server access */
     credentials;
+    /** Base URL for all non-absolute requests */
     base_url;
+    /**
+     * `openid-client` configuration metadata (either dervied from
+     * {@link credentials}) or requested from the well-known OpenID configuration
+     * endpoint of the `issuer`
+     */
     config;
+    /** Optional request components to inject */
     inject;
-    views;
+    /** Optional configuration options for web server listening for redirect */
+    localhostOptions;
+    /** Optional {@link TokenStorage} implementation to manage tokens */
+    storage;
+    /** Current response to an access token grant request, if available */
     token;
+    /** Mutex preventing multiple simultaneous access token grant requests */
     tokenLock = new Mutex();
-    storage;
-    constructor({ name, credentials, base_url, views, inject, storage }) {
+    /** @see {@link Options.Client} */
+    constructor({ name, reason, credentials, base_url, inject, storage, localhost }) {
         super();
-        this.name = name;
+        this._name = name;
+        this.reason = reason;
         this.credentials = credentials;
         this.base_url = base_url;
-        this.views = views;
+        this.localhostOptions = localhost;
         this.inject = inject;
         this.storage = storage;
     }
-    clientName() {
-        if (this.name && this.name.length > 0) {
-            return this.name;
-        }
-        return 'oauth2-cli';
-    }
-    get redirect_uri() {
-        return this.credentials.redirect_uri;
-    }
     /**
-     * @throws IndeterminateConfiguration if provided credentials combined with
-     *   OpenID discovery fail to generate a complete configuration
+     * Build a client configuration either via `issuer` discovery or from provided
+     * `credentials`
      */
     async getConfiguration() {
-        let error = undefined;
+        let discovery = undefined;
         if (!this.config && this.credentials.issuer) {
             try {
-                this.config = await OpenIDClient.discovery(requestish.URL.from(this.credentials.issuer), this.credentials.client_id, { client_secret: this.credentials.client_secret });
+                this.config = await OpenIDClient.discovery(URL.from(this.credentials.issuer), this.credentials.client_id, { client_secret: this.credentials.client_secret });
             }
-            catch (e) {
-                error = e;
+            catch (error) {
+                discovery = error;
             }
         }
         if (!this.config && this.credentials?.authorization_endpoint) {
             this.config = new OpenIDClient.Configuration({
-                issuer: `https://${requestish.URL.from(this.credentials.authorization_endpoint).hostname}`,
-                authorization_endpoint: requestish.URL.toString(this.credentials.authorization_endpoint),
-                token_endpoint: requestish.URL.toString(this.credentials.token_endpoint ||
+                issuer: `https://${URL.from(this.credentials.authorization_endpoint).hostname}`,
+                authorization_endpoint: URL.toString(this.credentials.authorization_endpoint),
+                token_endpoint: URL.toString(this.credentials.token_endpoint ||
                     this.credentials.authorization_endpoint)
             }, this.credentials.client_id, { client_secret: this.credentials.client_secret });
         }
         if (!this.config) {
-            throw new Error(`The ${this.clientName()} configuration could not be constructed from provided credentials.`, {
+            throw new Error(`Client configuration for ${this.name} could not be discovered or derived from credentials`, {
                 cause: {
                     credentials: this.credentials,
-                    'OpenID configuration result': error
+                    discovery
                 }
             });
         }
         return this.config;
     }
-    async getParameters(session) {
-        const params = requestish.URLSearchParams.merge(this.inject?.search, session.inject?.search) || new URLSearchParams();
-        params.set('redirect_uri', requestish.URL.toString(this.credentials.redirect_uri));
+    /**
+     * Build a URL to redirect the user-agent to, in order to request
+     * authorization at the Authorization Server
+     *
+     * @param session Contains the current `state` and `code_verifier` for the
+     *   Authorization Code flow session
+     */
+    async buildAuthorizationUrl(session) {
+        const params = URLSearchParams.from(this.inject?.search);
+        params.set('redirect_uri', URL.toString(this.credentials.redirect_uri));
         params.set('code_challenge', await OpenIDClient.calculatePKCECodeChallenge(session.code_verifier));
         params.set('code_challenge_method', 'S256');
         params.set('state', session.state);
         if (this.credentials.scope) {
-            params.set('scope', Scope.toString(this.credentials.scope));
+            params.set('scope', Token.Scope.toString(this.credentials.scope));
         }
-        return params;
-    }
-    async getAuthorizationUrl(session) {
-        return OpenIDClient.buildAuthorizationUrl(await this.getConfiguration(), await this.getParameters(session));
-    }
-    createSession({ views, ...options }) {
-        return new Session({
-            client: this,
-            views: views || this.views,
-            ...options
-        });
+        return OpenIDClient.buildAuthorizationUrl(await this.getConfiguration(), params);
     }
+    /** Does the client hold or have access to an unexpired API access token? */
     async isAuthorized() {
         if (this.token?.expiresIn()) {
             return true;
@@ -109,68 +117,118 @@ export class Client extends EventEmitter {
             });
         }
     }
-    async authorize(options = {}) {
-        const session = this.createSession(options);
+    /** Start interactive authorization for API access with the user */
+    async authorize() {
+        return await this.tokenLock.runExclusive(async () => {
+            console.log('running authorize from external call');
+            return await this._authorize();
+        });
+    }
+    /**
+     * Start interactive authorization for API access with the user _without_
+     * checking for tokenLock mutex
+     *
+     * Should be called _only_ from within a `tokenLock.runExclusive()` callback
+     */
+    async _authorize() {
+        const session = new Localhost.Server({
+            client: this,
+            reason: this.reason,
+            ...this.localhostOptions
+        });
         const token = await this.save(await session.authorizationCodeGrant());
         return token;
     }
-    async handleAuthorizationCodeRedirect(req, session) {
+    /**
+     * Validate the authorization response and then executes the !"Authorization
+     * Code Grant" at the Authorization Server's token endpoint to obtain an
+     * access token. ID Token and Refresh Token are also optionally issued by the
+     * server.
+     *
+     * @param request Authorization Server's request to the Localhost redirect
+     *   server
+     * @param session Contains the current `state` and `code_verifier` for the
+     *   Authorization Code flow session
+     */
+    async handleAuthorizationCodeRedirect(request, session) {
         try {
-            /**
-             * Do _NOT_ await this promise: the WebServer needs to send the
-             * authorization complete response asynchronously before this can resolve,
-             * and awaiting session.resolve() will block that response.
-             */
-            session.resolve(await OpenIDClient.authorizationCodeGrant(await this.getConfiguration(), new URL(req.url, this.redirect_uri), {
+            return await OpenIDClient.authorizationCodeGrant(await this.getConfiguration(), gcrtl.expand(request.url, this.credentials.redirect_uri), {
                 pkceCodeVerifier: session.code_verifier,
                 expectedState: session.state
             }, this.inject?.search
-                ? requestish.URLSearchParams.from(this.inject.search)
-                : undefined));
+                ? URLSearchParams.from(this.inject.search)
+                : undefined);
         }
         catch (cause) {
-            session.reject(new Error(`Error making ${this.clientName()} Authorization Code Grant request`, { cause }));
+            throw new Error(`${this.name} authorization code grant failed.`, {
+                cause
+            });
         }
     }
-    async refreshTokenGrant({ refresh_token = this.token?.refresh_token, inject: request } = {}) {
+    /**
+     * Perform an OAuth 2.0 Refresh Token Grant at the Authorization Server's
+     * token endpoint, allowing the client to obtain a new access token using a
+     * valid `refresh_token`.
+     *
+     * @see {@link Options.Refresh}
+     */
+    async refreshTokenGrant({ refresh_token = this.token?.refresh_token, inject } = {}) {
         if (!refresh_token && !this.token && this.storage) {
             refresh_token = await this.storage.load();
         }
         if (!refresh_token || refresh_token === '') {
             return undefined;
         }
-        const token = await OpenIDClient.refreshTokenGrant(await this.getConfiguration(), refresh_token, this.inject?.search
-            ? requestish.URLSearchParams.from(this.inject.search)
-            : undefined, {
-            // @ts-expect-error 2322 undocumented arg pass-through to oauth4webapi
-            headers: requestish.Headers.merge(this.headers, request?.headers)
-        });
-        return await this.save(token);
+        try {
+            const token = await OpenIDClient.refreshTokenGrant(await this.getConfiguration(), refresh_token, this.inject?.search
+                ? URLSearchParams.from(this.inject.search)
+                : undefined, {
+                // @ts-expect-error 2322 undocumented arg pass-through to oauth4webapi
+                headers: Headers.merge(this.headers, inject?.headers)
+            });
+            return await this.save(token);
+        }
+        catch (cause) {
+            throw new Error(`Could not refresh access to ${this.name}`, { cause });
+        }
     }
     /**
      * Get an unexpired access token
      *
      * Depending on provided and/or stored access token and refresh token values,
      * this may require interactive authorization
+     *
+     * @see {@link Options.GetToken}
      */
     async getToken({ token, inject: request } = {}) {
         return await this.tokenLock.runExclusive(async () => {
             token = token || this.token;
             if (!this.token?.expiresIn() && this.storage) {
-                this.token = await this.refreshTokenGrant({ inject: request });
+                try {
+                    this.token = await this.refreshTokenGrant({ inject: request });
+                }
+                catch (_) {
+                    // token definitely expired and refrehing it failed
+                    this.token = undefined;
+                }
             }
             if (!this.token) {
-                this.token = await this.authorize({ inject: request });
+                this.token = await this._authorize();
             }
             return this.token;
         });
     }
-    /** @throws MissingAccessToken If response does not include `access_token` */
-    async save(token) {
-        this.token = token;
-        if (!token.access_token) {
-            throw new Error(`No access_token in response to ${this.clientName()}.`, {
-                cause: token
+    /**
+     * Persist `refresh_token` if Token.Storage is configured and `refresh_token`
+     * provided
+     *
+     * @throws If `response` does not include `access_token` property
+     */
+    async save(response) {
+        this.token = response;
+        if (!response.access_token) {
+            throw new Error(`${this.name} token response does not contain access_token`, {
+                cause: response
             });
         }
         if (this.storage && this.token.refresh_token) {
@@ -180,25 +238,30 @@ export class Client extends EventEmitter {
         return this.token;
     }
     /**
-     * @param url If an `issuer` has been defined, `url` accepts paths relative to
-     *   the `issuer` URL as well as absolute URLs
+     * Request a protected resource using the client's access token.
+     *
+     * This ensures that the access token is unexpired, and interactively requests
+     * user authorization if it has not yet been provided.
+     *
+     * @param url If an `base_url` or `issuer` has been defined, `url` accepts
+     *   paths relative to the `issuer` URL as well as absolute URLs
      * @param method Optional, defaults to `GET` unless otherwise specified
      * @param body Optional
      * @param headers Optional
-     * @param dPoPOptions Optional
+     * @param dPoPOptions Optional, see {@link OpenIDClient.DPoPOptions}
      */
     async request(url, method = 'GET', body, headers = {}, dPoPOptions) {
         try {
-            url = requestish.URL.from(url);
+            url = URL.from(url);
         }
         catch (error) {
             if (this.base_url || this.credentials.issuer) {
                 url = path.join(
                 // @ts-expect-error 2345 TS, I _just_ tested this!
-                requestish.URL.toString(this.base_url || this.credentials.issuer), requestish.URL.toString(url).replace(/^\/?/, ''));
+                URL.toString(this.base_url || this.credentials.issuer), URL.toString(url).replace(/^\/?/, ''));
             }
             else {
-                throw new Error(`Invalid request URL "${url}" to ${this.clientName()}`, {
+                throw new Error(`${this.name} request url invalid`, {
                     cause: {
                         base_url: this.base_url,
                         issuer: this.credentials.issuer,
@@ -207,37 +270,35 @@ export class Client extends EventEmitter {
                 });
             }
         }
-        const request = async () => await OpenIDClient.fetchProtectedResource(await this.getConfiguration(), (await this.getToken()).access_token, requestish.URL.from(requestish.URLSearchParams.appendTo(url, this.inject?.search || {})), method, body, requestish.Headers.merge(this.inject?.headers, headers), dPoPOptions);
+        const request = async () => await OpenIDClient.fetchProtectedResource(await this.getConfiguration(), (await this.getToken()).access_token, URL.from(URLSearchParams.appendTo(url, this.inject?.search || {})), method, body, Headers.merge(this.inject?.headers, headers), dPoPOptions);
         try {
             return await request();
         }
-        catch (error) {
-            if (typeof error === 'object' &&
-                error !== null &&
-                'status' in error &&
-                error.status === 401) {
+        catch (cause) {
+            if (Error.isError(cause) && 'status' in cause && cause.status === 401) {
                 await this.authorize();
                 return await request();
             }
             else {
-                throw error;
+                throw new Error(`${this.name} request failed`, { cause });
             }
         }
     }
+    /** Parse a fetch response as JSON, typing it as J */
     async toJSON(response) {
         if (response.ok) {
-            return (await response.json());
+            try {
+                return (await response.json());
+            }
+            catch (cause) {
+                throw new Error(`${this.name} response could not be parsed as JSON`, {
+                    cause
+                });
+            }
         }
         else {
-            throw new Error(`The response could not be parsed as JSON by ${this.clientName()}.`, {
-                cause: {
-                    response: {
-                        status: response.status,
-                        statusText: response.statusText,
-                        headers: Object.fromEntries(response.headers?.entries() || []),
-                        body: response.text ? await response.text() : response.body
-                    }
-                }
+            throw new Error(`${this.name} response status not ok`, {
+                cause: { response }
             });
         }
     }
@@ -248,9 +309,25 @@ export class Client extends EventEmitter {
     async requestJSON(url, method = 'GET', body, headers = {}, dPoPOptions) {
         return await this.toJSON(await this.request(url, method, body, headers, dPoPOptions));
     }
+    /**
+     * Request a protected resource using the client's access token.
+     *
+     * This ensures that the access token is unexpired, and interactively requests
+     * user authorization if it has not yet been provided.
+     *
+     * @param input If a `base_url` or `issuer` has been defined, `url` accepts
+     *   paths relative to the `issuer` URL as well as absolute URLs
+     * @param init Optional
+     * @param dPoPOptions Optional, see {@link OpenIDClient.DPoPOptions}
+     * @see {@link request} for which this is an alias for {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API Fetch API}-style requests
+     */
     async fetch(input, init, dPoPOptions) {
-        return await this.request(input, init?.method, await requestish.Body.from(init?.body), requestish.Headers.from(init?.headers), dPoPOptions);
+        return await this.request(input, init?.method, await Body.from(init?.body), Headers.from(init?.headers), dPoPOptions);
     }
+    /**
+     * Returns the result of {@link fetch} as a parsed JSON object, optionally
+     * typed as `J`
+     */
     async fetchJSON(input, init, dPoPOptions) {
         return await this.toJSON(await this.fetch(input, init, dPoPOptions));
     }

package/dist/Credentials.d.ts

@@ -1,16 +1,48 @@
-import * as requestish from 'requestish';
-import * as Scope from './Scope.js';
+import { URL } from 'requestish';
+import { Scope } from './Token/index.js';
 export type Credentials = {
+    /** OAuth 2.0 / OpenID Connect `client_id` value */
     client_id: string;
+    /** OAuth 2.0 / OpenID Connect `client_secret` value */
     client_secret: string;
-    redirect_uri: requestish.URL.ish;
+    /**
+     * OAuth 2.0 / OpenID Connect `redirect_uri` value
+     *
+     * This must either be a URL of the form `http://localhost` or redirect to
+     * `http://localhost` for the client to be able to provide support for it. If
+     * SSL encryption is required, you must provide that configuration
+     * independently.
+     */
+    redirect_uri: URL.ish;
+    /** OAuth 2.0 / OpenID Connect access `scope` value */
     scope?: Scope.ish;
 } & ({
-    issuer?: requestish.URL.ish;
-    authorization_endpoint: requestish.URL.ish;
-    token_endpoint: requestish.URL.ish;
+    /**
+     * Optional OpenID Connect `issuer` to use for the well-known URL
+     * discovery process
+     */
+    issuer?: URL.ish;
+    /**
+     * OAuth 2.0 `authorization_endpoint` URL to for during Authorization Code
+     * flow
+     */
+    authorization_endpoint: URL.ish;
+    /**
+     * OAuth 2.0 `authorization_endpoint` URL to for during Authorization Code
+     * flow
+     */
+    token_endpoint: URL.ish;
 } | {
-    issuer: requestish.URL.ish;
-    authorization_endpoint?: requestish.URL.ish;
-    token_endpoint?: requestish.URL.ish;
+    /** OpenID Connect `issuer` to use for the well-known URL discovery process */
+    issuer: URL.ish;
+    /**
+     * Optional OAuth 2.0 `authorization_endpoint` URL to for during
+     * Authorization Code flow
+     */
+    authorization_endpoint?: URL.ish;
+    /**
+     * Optional OAuth 2.0 `authorization_endpoint` URL to for during
+     * Authorization Code flow
+     */
+    token_endpoint?: URL.ish;
 });

package/dist/Injection.d.ts

@@ -1,21 +1,22 @@
-import * as requestish from 'requestish';
-import * as Scope from './Scope.js';
+import { Body, Headers, URLSearchParams } from 'requestish';
+import { Scope } from './Token/index.js';
+/** Request components to inject when communicating with the API server */
 export type Injection = {
     /**
      * Search query parameters to include in server request (may be ovewritten by
      * computed values such as `state` or `challenge_code`)
      */
-    search?: requestish.URLSearchParams.ish;
+    search?: URLSearchParams.ish;
     /**
      * HTTP headers to include in server request (may be overwritten by computed
      * values such as `Authorization: Bearer <token>`)
      */
-    headers?: requestish.Headers.ish;
+    headers?: Headers.ish;
     /**
      * HTTP request body parameters to include in server request (if request
      * method allows)
      */
-    body?: requestish.Body.ish;
+    body?: Body.ish;
     /** Specific scope or scopes */
     scope?: Scope.ish;
 };

package/dist/Localhost/Defaults.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_LAUNCH_ENDPOINT = "/oauth2-cli/authorize";

package/dist/Localhost/Defaults.js

@@ -0,0 +1 @@
+export const DEFAULT_LAUNCH_ENDPOINT = '/oauth2-cli/authorize';

package/dist/Localhost/Options.d.ts

@@ -0,0 +1,28 @@
+import { PathString } from '@battis/descriptive-types';
+import { Client } from '../index.js';
+export type Options = {
+    client: Client;
+    /** Human-readable name of the app requesting API authorization */
+    reason?: string;
+    /** See {@link Session.setViews setViews()} */
+    views?: PathString;
+    /**
+     * Local web server launch endpoint
+     *
+     * This is separate and distinct from the OpenID/OAuth server's authorization
+     * endpoint. This endpoint is the first path that the user is directed to in
+     * their browser. It can present an explanation of what is being authorized
+     * and why. By default it redirects to the OpenID/OAuth server's authorization
+     * URL, the first step in the Authorization Code Grant flow.
+     */
+    launch_endpoint?: PathString;
+    /**
+     * The number of milliseconds of inactivity before a socket is presumed to
+     * have timed out. This can be reduced to limit potential wait times during
+     * interactive authentication, but must still be long enough to allow time for
+     * the authorization code to be exchanged for an access token.
+     *
+     * Defaults to 1000 milliseconds
+     */
+    timeout?: number;
+};

package/dist/Localhost/Options.js

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

package/dist/Localhost/Server.d.ts

@@ -0,0 +1,59 @@
+import { PathString } from '@battis/descriptive-types';
+import { Request, Response } from 'express';
+import * as Token from '../Token/index.js';
+import { Options } from './Options.js';
+/**
+ * Minimal HTTP server running on localhost to handle the redirect step of
+ * OpenID/OAuth flows
+ */
+export declare class Server {
+    private static activePorts;
+    /** PKCE code_verifier */
+    readonly code_verifier: string;
+    /** OAuth 2.0 state (if PKCE is not supported) */
+    readonly state: string;
+    private client;
+    private reason;
+    private views?;
+    private packageViews;
+    private spinner;
+    protected readonly port: string;
+    readonly launch_endpoint: PathString;
+    private server;
+    private resolveAuthorizationCodeFlow?;
+    private rejectAuthorizationCodeFlow?;
+    constructor({ reason, client, views, launch_endpoint, timeout }: Options);
+    authorizationCodeGrant(): Promise<Token.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: PathString): void;
+    protected render(res: Response, template: string, data?: Record<string, unknown>): Promise<boolean>;
+    /** Handles request to `/authorize` */
+    protected handleAuthorizationEndpoint(req: Request, res: Response): Promise<void>;
+    /** Handles request to `redirect_uri` */
+    protected handleRedirect(req: Request, res: Response): Promise<void>;
+    /** Shut down web server */
+    close(): Promise<void>;
+}