oauth2-cli 0.8.9 → 1.0.0

package/CHANGELOG.md

@@ -2,12 +2,31 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
-## [0.8.9](https://github.com/battis/oauth2-cli/compare/oauth2-cli/0.8.8...oauth2-cli/0.8.9) (2026-02-19)
+## [1.0.0](https://github.com/battis/oauth2-cli/compare/oauth2-cli/0.8.9...oauth2-cli/1.0.0) (2026-02-20)
+
+### ⚠ BREAKING CHANGES
+
+- rename WebServer -> Localhost, authorize.ejs -> launch.ejs
+- simplify access to client name by making it (only) a read-only property
+- correctly expand gcrtl redirect_uri when requesting access token
+
+### Features
 
+- auto-launch authorization flow in browser ([140e58e](https://github.com/battis/oauth2-cli/commit/140e58ea4c7a9c8d9c53624929e944d2ced1bd2e))
+- human-readable reason for authorizing access ([0cce8c2](https://github.com/battis/oauth2-cli/commit/0cce8c2e13213e92befc4f58c81e6d7f9637ea63))
+- rename WebServer -> Localhost, authorize.ejs -> launch.ejs ([09723a8](https://github.com/battis/oauth2-cli/commit/09723a81640cb8ad0e767584a81b9b56f5a617b2))
+- simplify access to client name by making it (only) a read-only property ([401c870](https://github.com/battis/oauth2-cli/commit/401c870071c0e9ffc65282e8c42270dff6e897a2))
+
+### Bug Fixes
+
+- correctly expand gcrtl redirect_uri when requesting access token ([387f9d8](https://github.com/battis/oauth2-cli/commit/387f9d83b81052fd19d80f7e7ff984390a90c822)), closes [#22](https://github.com/battis/oauth2-cli/issues/22)
+- re-authorize if refresh token grant fails ([4fb42bb](https://github.com/battis/oauth2-cli/commit/4fb42bb1f1fa65b253938c051b29799cdbd058bc))
+
+## [0.8.9](https://github.com/battis/oauth2-cli/compare/oauth2-cli/0.8.8...oauth2-cli/0.8.9) (2026-02-19)
 
 ### Bug Fixes
 
-* further refinement in debug logging ([568e563](https://github.com/battis/oauth2-cli/commit/568e563bc0a918cd9741951654db685488f10330))
+- further refinement in debug logging ([568e563](https://github.com/battis/oauth2-cli/commit/568e563bc0a918cd9741951654db685488f10330))
 
 ## [0.8.8](https://github.com/battis/oauth2-cli/compare/oauth2-cli/0.8.7...oauth2-cli/0.8.8) (2026-02-19)
 

package/README.md

@@ -1,6 +1,6 @@
 # oauth2-cli
 
-Acquire API access tokens via OAuth 2.0 within CLI tools
+Acquire API access tokens via OAuth 2.0 / OpenID Connect within CLI tools
 
 [![npm version](https://badge.fury.io/js/oauth2-cli.svg)](https://badge.fury.io/js/oauth2-cli)
 [![Module type: ESM](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://nodejs.org/api/esm.html)
@@ -21,11 +21,15 @@ type ExpectedResponse = {
 };
 
 const client = new Client({
-  client_id: 'm3C6dGQJPJrvgwN97mTP4pWVH9smZGrr',
-  client_secret: '2XUktyxU2KQmQAoVHxQXNaHZ4G7XqJdP',
-  redirect_uri: 'http://localhost:3000/example/redirect',
-  authorization_endpoint: 'https://example.com/oauth2/auth',
-  token_endpoint: 'https://example.com/oauth2/token',
+  name: 'Example API',
+  reason: 'an example script',
+  credentials: {
+    client_id: 'm3C6dGQJPJrvgwN97mTP4pWVH9smZGrr',
+    client_secret: '2XUktyxU2KQmQAoVHxQXNaHZ4G7XqJdP',
+    redirect_uri: 'http://localhost:3000/example/redirect',
+    authorization_endpoint: 'https://example.com/oauth2/auth',
+    token_endpoint: 'https://example.com/oauth2/token'
+  },
   storage: new FileStorage('/path/to/token/file.json');
 });
 console.log(
@@ -37,17 +41,29 @@ Broadly speaking, having provided the configuration, the client is immediately r
 
 ### Instantiate a `Client`
 
-A `Client` requires some minimal information in order to interact with an OAuth 2.0 authorized API. The OAuth 2.0 base set is a `client_id`, `client_secret`, `authorization_endpoint`, `token_endpoint`, and a `redirect_uri`. For an OpenID-authenticated API, you could provide a `client_id`, `client_secret`, `issuer`, and `redirect_uri` and the Client will query the issuer for further details regarding required connection parameters (it is built on to of [openid-client](https://www.npmjs.com/package/openid-client)).
+#### `credentials`
 
-In both cases, the token can be persisted by passing an implementation of [`Token.Storage`](https://github.com/battis/oauth2-cli/blob/main/packages/oauth2-cli/src/Token/TokenStorage.ts), such as [`FileStorage`](https://github.com/battis/oauth2-cli/blob/main/packages/oauth2-cli/src/Token/FileStorage.ts) which expects a path to a location to store a JSON file of access token data. _There are more secure ways to store your tokens, such as [@oauth2-cli/qui-cli](https://www.npmjs.com/package/@oauth2-cli/qui-cli)'s [`EnvironmentStorage`](https://github.com/battis/oauth2-cli/blob/main/packages/qui-cli/src/EnvironmentStorage.ts) which can be linked to a [1Password vault](https://github.com/battis/qui-cli/tree/main/packages/env#1password-integration)._
+A `Client` requires some minimal information in order to interact with an OAuth 2.0 authorized API. The OAuth 2.0 base `credentials` set is a `client_id`, `client_secret`, `authorization_endpoint`, `token_endpoint`, and a `redirect_uri`. For an OpenID-authenticated API, you could provide a `client_id`, `client_secret`, `issuer`, and `redirect_uri` and the Client will query the issuer for further details regarding required connection parameters (it is built on to of [openid-client](https://www.npmjs.com/package/openid-client)).
 
-#### `redirect_uri` to Localhost
+#### `name` and `reason`
+
+It is strongly recommended that you provide a human-readable `name` for the client that will be used in user messages explaining _what_ is being accessed (e.g. the name of the API or service) and a human-readable `reason` for the user to provide this access (e.g. the name of your app or script). Messages are structured in the manner:
+
+> ...to authorize access to `name` for `reason`, do this...
+
+#### `storage`
+
+The `refresh_token` can be persisted by passing an implementation of [`Token.Storage`](https://github.com/battis/oauth2-cli/blob/main/packages/oauth2-cli/src/Token/TokenStorage.ts), such as [`FileStorage`](https://github.com/battis/oauth2-cli/blob/main/packages/oauth2-cli/src/Token/FileStorage.ts) which expects a path to a location to store a JSON file of access token data. _There are more secure ways to store your tokens, such as [@oauth2-cli/qui-cli](https://www.npmjs.com/package/@oauth2-cli/qui-cli)'s [`EnvironmentStorage`](https://github.com/battis/oauth2-cli/blob/main/packages/qui-cli/src/EnvironmentStorage.ts) which can be linked to a [1Password vault](https://github.com/battis/qui-cli/tree/main/packages/env#1password-integration)._
+
+## Registering localhost redirect URLs
+
+### `redirect_uri` to Localhost
 
 Since the `redirect_uri` is receiving the authorization code in the Authorization Code token flow, the Client needs to be able to "catch" that redirect. The easy way to do this is to register a localhost address with the API (e.g. `http://localhost:3000/my/redirect/path`). When such a redirect URI is given to the client, it stands up (briefly) a local web server to receive that request at the port and path provided.
 
 Not every API accepts a `localhost` redirect (it creates the possibility of CORS exploits that could lead to XSS vulnerabilities). For these APIs, using [gcrtl](https://github.com/battis/google-cloud-run-to-localhost#readme) or a similar system will work as well. (In the specific case of `gcrtl`, `oauth2-cli` will trim the leading `/http/localhost:<port>` from provided `redirect_uri` and expect the _remainder_ of the path.)
 
-#### `http` protocol
+### `http` protocol
 
 If you would prefer an `https` connection to localhost, you have to roll your own SSL certificate.
 
@@ -75,7 +91,11 @@ class Client {
 
 [`requestish.URL.ish`](https://www.npmjs.com/package/requestish) are more forgiving types accepting not just those specific types, but reasonable facsimiles of them.
 
-### `requestJSON<T>()`
+#### `base_url` and `issuer` for relative paths
+
+If you would prefer to make requests to relative paths, rather than absolute paths, either configure a `base_url` or include an `issuer` in the `credentials` when instantiating the client. A `base_url` will preempt an `issuer`, if both are defined (handy for when the `issuer` is a different subdomain than the API endpoints).
+
+### `requestJSON<J>()`
 
 Given that many APIs return JSON-formatted responses, it is convenient to just get that JSON (optionally pre-typed based on what you expect to receive) rather than having to process the response yourself.
 
@@ -84,7 +104,7 @@ class Client {
   // ...
 
   public async requestJSON<
-    T extends OpenIDClient.JsonValue = OpenIDClient.JsonValue
+    J extends OpenIDClient.JsonValue = OpenIDClient.JsonValue
   >(
     url: requestish.URL.ish,
     method = 'GET',
@@ -97,6 +117,10 @@ class Client {
 }
 ```
 
+### `fetch()` and `fetchJSON<J>()`
+
+Aliases for `request()` and `requestJSON<J>()` that use [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)-style arguments.
+
 ## Examples
 
 [Refer to examples for more detailed usage.](https://github.com/battis/oauth2-cli/tree/main/examples/oauth2-cli#readme)

package/dist/Client.d.ts

@@ -1,122 +1,146 @@
-import { PathString } from '@battis/descriptive-types';
 import { JSONValue } from '@battis/typescript-tricks';
 import { Request } from 'express';
 import { EventEmitter } from 'node:events';
 import * as OpenIDClient from 'openid-client';
-import * as requestish from 'requestish';
+import { Headers, URL } from 'requestish';
 import { Credentials } from './Credentials.js';
 import { Injection } from './Injection.js';
-import { Session, SessionOptions } from './Session.js';
+import * as Localhost from './Localhost/index.js';
+import * as Options from './Options.js';
 import * as Token from './Token/index.js';
 /**
- * A generic `redirect_uri` to use if the server does not require pre-registered
- * `redirect_uri` values
+ * 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
  */
-export declare const DEFAULT_REDIRECT_URI = "http://localhost:3000/oauth2-cli/redirect";
-export type ClientOptions<C extends Credentials = Credentials> = {
+export declare class Client<C extends Credentials = Credentials> extends EventEmitter {
+    static readonly TokenEvent = "token";
+    private _name?;
     /** Human-readable name for client in messages */
-    name?: string;
+    get name(): string;
+    /** Human-readable reason for authorization in messages */
+    private reason?;
     /** Credentials for server access */
     credentials: C;
-    /** Optional request components to inject */
-    inject?: {
-        search?: requestish.URLSearchParams.ish;
-        headers?: requestish.Headers.ish;
-        body?: requestish.Body.ish;
-    };
     /** Base URL for all non-absolute requests */
-    base_url?: requestish.URL.ish;
+    base_url?: URL.ish;
     /**
-     * Optional absolute path to EJS view templates directory, see
-     * [WebServer.setViews()](./Webserver.ts)
+     * `openid-client` configuration metadata (either dervied from
+     * {@link credentials}) or requested from the well-known OpenID configuration
+     * endpoint of the `issuer`
      */
-    views?: PathString;
+    protected config?: OpenIDClient.Configuration;
+    /** Optional request components to inject */
+    protected inject?: Injection;
+    /** Optional configuration options for web server listening for redirect */
+    private localhostOptions?;
     /** Optional {@link TokenStorage} implementation to manage tokens */
-    storage?: Token.Storage;
-};
-type RefreshOptions = {
+    private storage?;
+    /** Current response to an access token grant request, if available */
+    private token?;
+    /** Mutex preventing multiple simultaneous access token grant requests */
+    private tokenLock;
+    /** @see {@link Options.Client} */
+    constructor({ name, reason, credentials, base_url, inject, storage, localhost }: Options.Client<C>);
+    /**
+     * Build a client configuration either via `issuer` discovery or from provided
+     * `credentials`
+     */
+    getConfiguration(): Promise<OpenIDClient.Configuration>;
     /**
-     * Optional refresh token
+     * Build a URL to redirect the user-agent to, in order to request
+     * authorization at the Authorization Server
      *
-     * If using {@link TokenStorage}, the refresh token should be stored with the
-     * access token and does not need to be separately managed and stored
+     * @param session Contains the current `state` and `code_verifier` for the
+     *   Authorization Code flow session
      */
-    refresh_token?: string;
-    /** Additional request injection for refresh grant flow */
-    inject?: Injection;
-};
-type GetTokenOptions = {
+    buildAuthorizationUrl(session: Localhost.Server): Promise<URL>;
+    /** Does the client hold or have access to an unexpired API access token? */
+    isAuthorized(): Promise<boolean>;
+    /** Start interactive authorization for API access with the user */
+    authorize(): Promise<Token.Response>;
     /**
-     * Optional access token
+     * Start interactive authorization for API access with the user _without_
+     * checking for tokenLock mutex
      *
-     * If using {@link TokenStorage}, the access token does not need to be
-     * separately managed and stored
+     * Should be called _only_ from within a `tokenLock.runExclusive()` callback
      */
-    token?: Token.Response;
+    private _authorize;
     /**
-     * Additional request injection for authorization code grant and/or refresh
-     * grant flows
+     * 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
      */
-    inject?: Injection;
-};
-/**
- * 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
- */
-export declare class Client<C extends Credentials = Credentials> extends EventEmitter {
-    static readonly TokenEvent = "token";
-    readonly name?: string;
-    protected credentials: C;
-    protected base_url?: requestish.URL.ish;
-    protected config?: OpenIDClient.Configuration;
-    protected inject?: Injection;
-    protected views?: PathString;
-    private token?;
-    private tokenLock;
-    private storage?;
-    constructor({ name, credentials, base_url, views, inject, storage }: ClientOptions<C>);
-    clientName(): string;
-    get redirect_uri(): requestish.URL.ish;
+    handleAuthorizationCodeRedirect(request: Request, session: Localhost.Server): Promise<OpenIDClient.TokenEndpointResponse & OpenIDClient.TokenEndpointResponseHelpers>;
     /**
-     * @throws IndeterminateConfiguration if provided credentials combined with
-     *   OpenID discovery fail to generate a complete configuration
+     * 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}
      */
-    getConfiguration(): Promise<OpenIDClient.Configuration>;
-    protected getParameters(session: Session): Promise<URLSearchParams>;
-    getAuthorizationUrl(session: Session): Promise<URL>;
-    createSession({ views, ...options }: Omit<SessionOptions, 'client'>): Session;
-    isAuthorized(): Promise<boolean>;
-    authorize(options?: Omit<SessionOptions, 'client'>): Promise<Token.Response>;
-    handleAuthorizationCodeRedirect(req: Request, session: Session): Promise<void>;
-    protected refreshTokenGrant({ refresh_token, inject: request }?: RefreshOptions): Promise<Token.Response | undefined>;
+    protected refreshTokenGrant({ refresh_token, inject }?: Options.Refresh): Promise<Token.Response | undefined>;
     /**
      * 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}
      */
-    getToken({ token, inject: request }?: GetTokenOptions): Promise<Token.Response>;
-    /** @throws MissingAccessToken If response does not include `access_token` */
-    protected save(token: Token.Response): Promise<Token.Response>;
+    getToken({ token, inject: request }?: Options.GetToken): Promise<Token.Response>;
     /**
-     * @param url If an `issuer` has been defined, `url` accepts paths relative to
-     *   the `issuer` URL as well as absolute URLs
+     * Persist `refresh_token` if Token.Storage is configured and `refresh_token`
+     * provided
+     *
+     * @throws If `response` does not include `access_token` property
+     */
+    protected save(response: Token.Response): Promise<Token.Response>;
+    /**
+     * 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}
      */
-    request(url: requestish.URL.ish, method?: string, body?: OpenIDClient.FetchBody, headers?: requestish.Headers.ish, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<Response>;
+    request(url: URL.ish, method?: string, body?: OpenIDClient.FetchBody, headers?: Headers.ish, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<Response>;
+    /** Parse a fetch response as JSON, typing it as J */
     private toJSON;
     /**
      * Returns the result of {@link request} as a parsed JSON object, optionally
      * typed as `J`
      */
-    requestJSON<J extends JSONValue = JSONValue>(url: requestish.URL.ish, method?: string, body?: OpenIDClient.FetchBody, headers?: requestish.Headers.ish, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<J>;
-    fetch(input: requestish.URL.ish, init?: RequestInit, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<Response>;
-    fetchJSON<J extends JSONValue = JSONValue>(input: requestish.URL.ish, init?: RequestInit, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<J>;
+    requestJSON<J extends JSONValue = JSONValue>(url: URL.ish, method?: string, body?: OpenIDClient.FetchBody, headers?: Headers.ish, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<J>;
+    /**
+     * 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
+     */
+    fetch(input: URL.ish, init?: RequestInit, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<Response>;
+    /**
+     * Returns the result of {@link fetch} as a parsed JSON object, optionally
+     * typed as `J`
+     */
+    fetchJSON<J extends JSONValue = JSONValue>(input: URL.ish, init?: RequestInit, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<J>;
 }
-export {};