oauth2-cli 0.5.0 → 0.6.0

package/dist/Errors/BadResponse.js

@@ -0,0 +1,7 @@
+export class BadResponse extends Error {
+    constructor(response) {
+        super(`Response error ${response.status}: ${response.statusText}`, {
+            cause: response
+        });
+    }
+}

package/dist/Errors/IndeterminateConfiguration.d.ts

@@ -0,0 +1,3 @@
+export declare class IndeterminateConfiguration extends Error {
+    constructor();
+}

package/dist/Errors/IndeterminateConfiguration.js

@@ -0,0 +1,5 @@
+export class IndeterminateConfiguration extends Error {
+    constructor() {
+        super('A configuration could not be determined from the provided credentials.');
+    }
+}

package/dist/Errors/MissingAccessToken.d.ts

@@ -0,0 +1,3 @@
+export declare class MissingAccessToken extends Error {
+    constructor();
+}

package/dist/Errors/MissingAccessToken.js

@@ -0,0 +1,5 @@
+export class MissingAccessToken extends Error {
+    constructor() {
+        super('No access token available.');
+    }
+}

package/dist/Errors/PortCollision.d.ts

@@ -0,0 +1,3 @@
+export declare class PortCollision extends Error {
+    constructor(port: string);
+}

package/dist/Errors/PortCollision.js

@@ -0,0 +1,5 @@
+export class PortCollision extends Error {
+    constructor(port) {
+        super(`Cannot start authorization: another process is already running at http://localhost:${port}.`);
+    }
+}

package/dist/Errors/index.d.ts

@@ -0,0 +1,4 @@
+export * from './BadResponse.js';
+export * from './IndeterminateConfiguration.js';
+export * from './MissingAccessToken.js';
+export * from './PortCollision.js';

package/dist/Errors/index.js

@@ -0,0 +1,4 @@
+export * from './BadResponse.js';
+export * from './IndeterminateConfiguration.js';
+export * from './MissingAccessToken.js';
+export * from './PortCollision.js';

package/dist/Request/Body.d.ts

@@ -0,0 +1,3 @@
+import { FetchBody } from 'openid-client';
+export type ish = FetchBody | FormData | Record<string, string> | RequestInit['body'];
+export declare function from(body: ish): Promise<FetchBody | undefined>;

package/dist/Request/Body.js

@@ -0,0 +1,19 @@
+import { isRecord } from '@battis/typescript-tricks';
+function isString(obj) {
+    return typeof obj === 'string';
+}
+export async function from(body) {
+    if (body === undefined ||
+        body === null ||
+        typeof body === 'string' ||
+        body instanceof ArrayBuffer ||
+        body instanceof ReadableStream ||
+        body instanceof Uint8Array ||
+        body instanceof URLSearchParams) {
+        return body;
+    }
+    else if (isRecord(body, isString, isString)) {
+        return new URLSearchParams(body);
+    }
+    return new Response(body).arrayBuffer();
+}

package/dist/Request/Headers.d.ts

@@ -0,0 +1,3 @@
+export type ish = Headers | NonNullable<RequestInit['headers']> | Record<string, string> | [string, string][];
+export declare function from(headers?: ish): Headers;
+export declare function merge(a?: ish, b?: ish): Headers | undefined;

package/dist/Request/Headers.js

@@ -0,0 +1,20 @@
+export function from(headers) {
+    if (headers instanceof Headers) {
+        return headers;
+    }
+    return new Headers(headers);
+}
+export function merge(a, b) {
+    if (a && !b) {
+        return from(a);
+    }
+    else if (!a && b) {
+        return from(b);
+    }
+    else if (a && b) {
+        const headers = from(a);
+        from(b).forEach((value, key) => headers.set(key, value));
+        return headers;
+    }
+    return undefined;
+}

package/dist/Request/Injection.d.ts

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

package/dist/Request/Injection.js

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

package/dist/Request/Scope.d.ts

@@ -0,0 +1,2 @@
+export type ish = string | string[];
+export declare function toString(scope: ish, separator?: string): string;

package/dist/Request/Scope.js

@@ -0,0 +1,6 @@
+export function toString(scope, separator = ' ') {
+    if (typeof scope === 'string') {
+        return scope;
+    }
+    return scope.join(separator);
+}

package/dist/Request/URL.d.ts

@@ -0,0 +1,4 @@
+import { URLString } from '@battis/descriptive-types';
+export type ish = URL | URLString;
+export declare function from(url: ish): URL;
+export declare function toString(url: ish): URLString;

package/dist/Request/URL.js

@@ -0,0 +1,12 @@
+export function from(url) {
+    if (url instanceof URL) {
+        return url;
+    }
+    return new URL(url);
+}
+export function toString(url) {
+    if (typeof url === 'string') {
+        return url;
+    }
+    return url.toString();
+}

package/dist/Request/URLSearchParams.d.ts

@@ -0,0 +1,6 @@
+import { ish as URLish } from './URL.js';
+export type ish = URLSearchParams | Record<string, string>;
+export declare function from(search: ish): URLSearchParams;
+export declare function toString(search: ish): string;
+export declare function merge(a?: ish, b?: ish): URLSearchParams | undefined;
+export declare function appendTo(url: URLish, search: ish): URLish;

package/dist/Request/URLSearchParams.js

@@ -0,0 +1,37 @@
+export function from(search) {
+    if (search instanceof URLSearchParams) {
+        return search;
+    }
+    return new URLSearchParams(search);
+}
+export function toString(search) {
+    const query = from(search).toString();
+    if (query.length) {
+        return `?${query}`;
+    }
+    return '';
+}
+export function merge(a, b) {
+    if (a && !b) {
+        return from(a);
+    }
+    else if (!a && b) {
+        return from(b);
+    }
+    else if (a && b) {
+        const search = from(a);
+        from(b).forEach((value, key) => search.set(key, value));
+        return search;
+    }
+    return undefined;
+}
+export function appendTo(url, search) {
+    if (url instanceof URL) {
+        const result = new URL(url);
+        result.search = toString(search);
+        return result;
+    }
+    else {
+        return url.replace(/(.+)(\?.*)?$/, `$1${toString(search)}`);
+    }
+}

package/dist/Request/index.d.ts

@@ -0,0 +1,6 @@
+export * as Body from './Body.js';
+export * as Headers from './Headers.js';
+export * from './Injection.js';
+export * as Scope from './Scope.js';
+export * as URL from './URL.js';
+export * as URLSearchParams from './URLSearchParams.js';

package/dist/Request/index.js

@@ -0,0 +1,6 @@
+export * as Body from './Body.js';
+export * as Headers from './Headers.js';
+export * from './Injection.js';
+export * as Scope from './Scope.js';
+export * as URL from './URL.js';
+export * as URLSearchParams from './URLSearchParams.js';

package/dist/Session.d.ts

@@ -0,0 +1,47 @@
+import { PathString } from '@battis/descriptive-types';
+import { Request } from 'express';
+import { Client } from './Client.js';
+import * as Req from './Request/index.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?: Req.Injection;
+};
+export type Resolver = (response?: Token.Response, error?: Error) => void | Promise<void>;
+export declare class Session {
+    private readonly 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?: Req.Injection;
+    private _resolve?;
+    private spinner?;
+    /**
+     * Method that resolves or rejects the promise returned from the
+     * {@link authorizationCodeGrant}
+     */
+    get resolve(): Resolver;
+    constructor({ client, views, inject: request }: SessionOptions);
+    /** Instantiate the web server that will listen for the out-of-band redirect */
+    createWebServer(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
+     */
+    authorizationCodeGrant(): Promise<Token.Response>;
+    /** OAuth 2.0 redirect_uri that this session is handling */
+    get redirect_uri(): Req.URL.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

@@ -0,0 +1,77 @@
+import { Colors } from '@qui-cli/colors';
+import * as gcrtl from 'gcrtl';
+import open from 'open';
+import * as OpenIDClient from 'openid-client';
+import ora from 'ora';
+import * as Errors from './Errors/index.js';
+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;
+    _resolve;
+    spinner;
+    /**
+     * Method that resolves or rejects the promise returned from the
+     * {@link authorizationCodeGrant}
+     */
+    get resolve() {
+        if (!this._resolve) {
+            throw new Error('callback is missing');
+        }
+        return this._resolve;
+    }
+    constructor({ client, views, inject: request }) {
+        this.client = client;
+        this.inject = request;
+        this.outOfBandRedirectServer = this.createWebServer({ views });
+    }
+    /** Instantiate the web server that will listen for the out-of-band redirect */
+    createWebServer(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
+     */
+    authorizationCodeGrant() {
+        return new Promise((resolve, reject) => {
+            this._resolve = async (response, error) => {
+                if (error) {
+                    reject(error);
+                }
+                if (response) {
+                    resolve(response);
+                }
+                else {
+                    reject(new Errors.MissingAccessToken());
+                }
+            };
+            const url = gcrtl
+                .expand(this.outOfBandRedirectServer.authorization_endpoint, this.client.redirect_uri)
+                .toString();
+            this.spinner = ora(`Waiting for interactive authorization at ${Colors.url(url)}`).start();
+            open(url);
+        });
+    }
+    /** 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?.succeed('Interactive authorization begun');
+        return await this.client.handleAuthorizationCodeRedirect(req, this);
+    }
+}

package/dist/{FileStorage.d.ts → Token/FileStorage.d.ts}

@@ -1,9 +1,8 @@
-import { Token } from './Token.js';
 import { TokenStorage } from './TokenStorage.js';
 export declare class FileStorage implements TokenStorage {
     private fileLock;
     private readonly filePath;
     constructor(filePath: string);
-    load(): Promise<Token | undefined>;
-    save(tokens: Token): Promise<void>;
+    load(): Promise<string | undefined>;
+    save(refresh_token: string): Promise<void>;
 }

package/dist/{FileStorage.js → Token/FileStorage.js}

@@ -1,7 +1,6 @@
 import { Mutex } from 'async-mutex';
 import fs from 'node:fs';
 import path from 'node:path';
-import { Token } from './Token.js';
 export class FileStorage {
     fileLock = new Mutex();
     filePath;
@@ -11,18 +10,18 @@ export class FileStorage {
     async load() {
         return await this.fileLock.runExclusive((async () => {
             if (fs.existsSync(this.filePath)) {
-                return Token.fromResponse(JSON.parse(fs.readFileSync(this.filePath).toString()));
+                return fs.readFileSync(this.filePath).toString();
             }
             return undefined;
         }).bind(this));
     }
-    async save(tokens) {
+    async save(refresh_token) {
         await this.fileLock.runExclusive((async () => {
             const dirPath = path.dirname(this.filePath);
             if (!fs.existsSync(dirPath)) {
                 fs.mkdirSync(dirPath, { recursive: true });
             }
-            fs.writeFileSync(this.filePath, JSON.stringify(tokens));
+            fs.writeFileSync(this.filePath, refresh_token);
         }).bind(this));
     }
 }

package/dist/Token/Response.d.ts

@@ -0,0 +1,2 @@
+import * as OpenIDClient from 'openid-client';
+export type Response = OpenIDClient.TokenEndpointResponse & OpenIDClient.TokenEndpointResponseHelpers;

package/dist/Token/Response.js

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

package/dist/Token/TokenStorage.d.ts

@@ -0,0 +1,4 @@
+export interface TokenStorage {
+    load(): Promise<string | undefined>;
+    save(refresh_token: string): Promise<void>;
+}

package/dist/Token/TokenStorage.js

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

package/dist/Token/addHelpers.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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;

package/dist/Token/addHelpers.js

@@ -0,0 +1,44 @@
+/**
+ * Reaching into the bowels of openid-client to be able to fully de-serialize a
+ * serialized token response
+ */
+import * as oauth from 'oauth4webapi';
+/** @see https://github.com/panva/openid-client/blob/79386b7f120dc9bdc7606886a26e4ea7d011ee51/src/index.ts#L1981-L2016 */
+function getHelpers(response) {
+    let exp = undefined;
+    if (response.expires_in !== undefined) {
+        const now = new Date();
+        now.setSeconds(now.getSeconds() + response.expires_in);
+        exp = now.getTime();
+    }
+    return {
+        expiresIn: {
+            __proto__: null,
+            value() {
+                if (exp) {
+                    const now = Date.now();
+                    if (exp > now) {
+                        return Math.floor((exp - now) / 1000);
+                    }
+                    return 0;
+                }
+                return undefined;
+            }
+        },
+        claims: {
+            __proto__: null,
+            value() {
+                try {
+                    return oauth.getValidatedIdTokenClaims(this);
+                }
+                catch {
+                    return undefined;
+                }
+            }
+        }
+    };
+}
+/** @see https://github.com/panva/openid-client/blob/79386b7f120dc9bdc7606886a26e4ea7d011ee51/src/index.ts#L2018-L2022 */
+export function addHelpers(response) {
+    Object.defineProperties(response, getHelpers(response));
+}

package/dist/Token/index.d.ts

@@ -0,0 +1,3 @@
+export * from './FileStorage.js';
+export * from './Response.js';
+export * from './TokenStorage.js';

package/dist/Token/index.js

@@ -0,0 +1,3 @@
+export * from './FileStorage.js';
+export * from './Response.js';
+export * from './TokenStorage.js';

package/dist/WebServer.d.ts

@@ -0,0 +1,64 @@
+import { PathString } from '@battis/descriptive-types';
+import { Request, Response } from 'express';
+import { Session } from './Session.js';
+export type WebServerOptions = {
+    session: Session;
+    /** See {@link WebServer.setViews setViews()} */
+    views?: PathString;
+    /**
+     * Local web server authorize 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.
+     */
+    authorize_endpoint?: PathString;
+};
+export declare const DEFAULT_AUTHORIZE_ENDPOINT = "/oauth2-cli/authorize";
+export interface WebServerInterface {
+    /** See {@link WebServerOptions} */
+    readonly authorization_endpoint: PathString;
+}
+/**
+ * Minimal HTTP server running on localhost to handle the redirect step of
+ * OpenID/OAuth flows
+ */
+export declare class WebServer implements WebServerInterface {
+    private static activePorts;
+    protected readonly session: Session;
+    private views?;
+    private packageViews;
+    protected readonly port: string;
+    readonly authorization_endpoint: PathString;
+    private server;
+    constructor({ session, views, authorize_endpoint }: WebServerOptions);
+    /**
+     * Set the path to folder of *.ejs templates
+     *
+     * Expected templates include:
+     *
+     * - `authorize.ejs` presents information prior to the authorization to the
+     *   user, and the user must follow `authorize_url` data property to
+     *   interactively initiate 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.
+     *
+     * @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>;
+    /** Close server */
+    close(): Promise<void>;
+}

package/dist/WebServer.js

@@ -0,0 +1,116 @@
+import express from 'express';
+import * as gcrtl from 'gcrtl';
+import fs from 'node:fs';
+import path from 'node:path';
+import * as Errors from './Errors/index.js';
+import * as Req from './Request/index.js';
+let ejs = undefined;
+try {
+    ejs = (await import('ejs')).default;
+}
+catch (_) {
+    // ignore error
+}
+export const DEFAULT_AUTHORIZE_ENDPOINT = '/oauth2-cli/authorize';
+/**
+ * Minimal HTTP server running on localhost to handle the redirect step of
+ * OpenID/OAuth flows
+ */
+export class WebServer {
+    static activePorts = [];
+    session;
+    views;
+    packageViews = '../views';
+    port;
+    authorization_endpoint;
+    server;
+    constructor({ session, views, authorize_endpoint = DEFAULT_AUTHORIZE_ENDPOINT }) {
+        this.session = session;
+        this.authorization_endpoint = authorize_endpoint;
+        this.views = views;
+        const url = Req.URL.from(this.session.redirect_uri);
+        this.port = url.port;
+        if (WebServer.activePorts.includes(this.port)) {
+            throw new Errors.PortCollision(url.port);
+        }
+        WebServer.activePorts.push(this.port);
+        const app = express();
+        app.get(this.authorization_endpoint, this.handleAuthorizationEndpoint.bind(this));
+        app.get(gcrtl.path(url), this.handleRedirect.bind(this));
+        this.server = app.listen(gcrtl.port(url));
+    }
+    /**
+     * Set the path to folder of *.ejs templates
+     *
+     * Expected templates include:
+     *
+     * - `authorize.ejs` presents information prior to the authorization to the
+     *   user, and the user must follow `authorize_url` data property to
+     *   interactively initiate 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.
+     *
+     * @param views Should be an absolute path
+     */
+    setViews(views) {
+        this.views = views;
+    }
+    async render(res, template, data = {}) {
+        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, 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 = await this.session.getAuthorizationUrl();
+        if (!(await this.render(res, 'authorize.ejs', { authorization_url }))) {
+            res.redirect(authorization_url);
+        }
+    }
+    /** Handles request to `redirect_uri` */
+    async handleRedirect(req, res) {
+        try {
+            await this.session.handleAuthorizationCodeRedirect(req);
+            if (!(await this.render(res, 'complete.ejs'))) {
+                res.send('You may close this window.');
+            }
+        }
+        catch (error) {
+            if (!(await this.render(res, 'error.ejs', { error }))) {
+                res.send(error);
+            }
+        }
+        finally {
+            this.close();
+        }
+    }
+    /** Close server */
+    async close() {
+        return new Promise((resolve, reject) => {
+            this.server.close((err) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    WebServer.activePorts.splice(WebServer.activePorts.indexOf(this.port), 1);
+                    resolve();
+                }
+            });
+        });
+    }
+}