feat: deprecate auth({ type: "token" }), code, state, redirectUrl strategy options, and setting user authentication in request hook (#163)

Author: gr2m

README.md

@@ -15,8 +15,8 @@ It implements authentication using an OAuth app’s client ID and secret as well
 - [`createOAuthAppAuth(options)`](#createoauthappauthoptions)
 - [`auth(options)`](#authoptions)
 - [Authentication object](#authentication-object)
-    - [OAuth authentication](#oauth-authentication)
-    - [OAuth access token authentication](#oauth-access-token-authentication)
+  - [OAuth authentication](#oauth-authentication)
+  - [OAuth access token authentication](#oauth-access-token-authentication)
 - [`auth.hook(request, route, parameters)` or `auth.hook(request, options)`](#authhookrequest-route-parameters-or-authhookrequest-options)
 - [Implementation details](#implementation-details)
 - [License](#license)
@@ -76,8 +76,8 @@ const appAuthentication = await auth({
 //   }
 // }
 
-const tokenAuthentication = await auth({
-  type: "token",
+const userAuthentication = await auth({
+  type: "oauth-user",
   code: "random123", // code from OAuth web flow, see https://git.io/fhd1D
   state: "mystate123",
 });
@@ -216,7 +216,7 @@ The async `auth()` method returned by `createOAuthAppAuth(options)` accepts the
         <code>string</code>
       </th>
       <td>
-        <strong>Required.</strong> Either <code>"oauth-app"</code> or <code>"token"</code>.
+        <strong>Required.</strong> Either <code>"oauth-app"</code> or <code>"oauth-user"</code>.
       </td>
     </tr>
     <tr>

src/auth.ts

@@ -1,13 +1,43 @@
 import btoa from "btoa-lite";
 
 import { getOAuthAccessToken } from "./get-oauth-access-token";
-import { State, AuthOptions, Authentication } from "./types";
+import {
+  State,
+  AuthAppOptions,
+  AuthTokenOptions,
+  DeprecatedAuthTokenOptions,
+  Authentication,
+} from "./types";
 
 export async function auth(
   state: State,
-  authOptions: AuthOptions
+  authOptions: AuthAppOptions
+): Promise<Authentication>;
+
+export async function auth(
+  state: State,
+  authOptions: AuthTokenOptions
+): Promise<Authentication>;
+
+/**
+ * @deprecated `type: "token"` is deprecate. Use `type: "oauth"` instead
+ */
+export async function auth(
+  state: State,
+  authOptions: DeprecatedAuthTokenOptions
+): Promise<Authentication>;
+
+export async function auth(
+  state: State,
+  authOptions: AuthAppOptions | AuthTokenOptions | DeprecatedAuthTokenOptions
 ): Promise<Authentication> {
   if (authOptions.type === "token") {
+    console.warn(
+      `[@octokit/auth-oauth-app] "{type: 'token'}" is deprecated, use "{type: 'oauth-user'}" instead`
+    );
+  }
+
+  if (authOptions.type === "token" || authOptions.type === "oauth-user") {
     const { token, scopes } = await getOAuthAccessToken(state, {
       auth: authOptions,
     });

src/get-oauth-access-token.ts

@@ -2,6 +2,7 @@ import { RequestError } from "@octokit/request-error";
 
 import {
   AuthTokenOptions,
+  DeprecatedAuthTokenOptions,
   RequestInterface,
   State,
   TokenWithScopes,
@@ -11,7 +12,7 @@ export async function getOAuthAccessToken(
   state: State,
   options: {
     request?: RequestInterface;
-    auth?: AuthTokenOptions;
+    auth?: AuthTokenOptions | DeprecatedAuthTokenOptions;
   }
 ): Promise<TokenWithScopes> {
   const authOptionsPassed = options.auth

src/hook.ts

@@ -58,6 +58,10 @@ export async function hook(
     return response;
   }
 
+  console.warn(
+    `[@octokit/auth-oauth-app] setting user authentication is deprecated. Use "@octokit/auth-oauth-user" instead`
+  );
+
   const { token } = await getOAuthAccessToken(state, { request });
   endpoint.headers.authorization = `token ${token}`;
 

src/index.ts

@@ -3,7 +3,12 @@ import { request } from "@octokit/request";
 
 import { auth } from "./auth";
 import { hook } from "./hook";
-import { StrategyOptions, AuthOptions, Authentication } from "./types";
+import {
+  StrategyOptions,
+  AuthOptions,
+  Authentication,
+  OAuthAppAuthInterface,
+} from "./types";
 import { VERSION } from "./version";
 
 export type Types = {
@@ -12,19 +17,36 @@ export type Types = {
   Authentication: Authentication;
 };
 
-export function createOAuthAppAuth(options: StrategyOptions) {
+const deprecatedStrategyOptions = ["code", "redirectUrl", "state"];
+
+export function createOAuthAppAuth(
+  options: StrategyOptions
+): OAuthAppAuthInterface {
+  const usedDeprecatedOptions = deprecatedStrategyOptions.filter(
+    (option) => option in options
+  );
+
+  if (usedDeprecatedOptions.length) {
+    console.warn(
+      `[@octokit/auth-oauth-app] "${usedDeprecatedOptions.join(
+        ", "
+      )}" strategy options are deprecated. Use "@octokit/auth-oauth-user" instead`
+    );
+  }
+
   const state = Object.assign(
     {
       request: request.defaults({
         headers: {
-          "user-agent": `octokit-auth-oauth-app.js/${VERSION} ${getUserAgent()}`
-        }
-      })
+          "user-agent": `octokit-auth-oauth-app.js/${VERSION} ${getUserAgent()}`,
+        },
+      }),
     },
     options
   );
 
+  // @ts-expect-error wtf
   return Object.assign(auth.bind(null, state), {
-    hook: hook.bind(null, state)
+    hook: hook.bind(null, state),
   });
 }

src/types.ts

@@ -20,17 +20,27 @@ export type StrategyOptions = {
   request?: RequestInterface;
 };
 
-type AuthAppOptions = {
+export type AuthAppOptions = {
   type: "oauth-app";
 };
 export type AuthTokenOptions = {
+  type: "oauth-user";
+  code?: string;
+  redirectUrl?: string;
+  state?: string;
+};
+/** @deprecated type: "token" is deprecated. Use type: "oauth-user" */
+export type DeprecatedAuthTokenOptions = {
   type: "token";
   code?: string;
   redirectUrl?: string;
   state?: string;
 };
 
-export type AuthOptions = AuthAppOptions | AuthTokenOptions;
+export type AuthOptions =
+  | AuthAppOptions
+  | AuthTokenOptions
+  | DeprecatedAuthTokenOptions;
 
 export type TokenWithScopes = {
   token: string;
@@ -53,3 +63,12 @@ export type State = StrategyOptions & {
   request: RequestInterface;
   token?: TokenWithScopes;
 };
+export interface OAuthAppAuthInterface {
+  (options?: AuthOptions): Promise<Authentication>;
+
+  hook(
+    request: OctokitTypes.RequestInterface,
+    route: OctokitTypes.Route | OctokitTypes.EndpointOptions,
+    parameters?: OctokitTypes.RequestParameters
+  ): Promise<OctokitTypes.OctokitResponse<any>>;
+}