docs: improve documentation, update security note

jasonraimondi · Jun 8, 2023 · 43ae819 · 43ae819
1 parent ed72b13
commit 43ae819
Show file tree

Hide file tree

Showing 6 changed files with 65 additions and 44 deletions.
diff --git a/README.md b/README.md
@@ -43,6 +43,12 @@ Save some eye strain, **use the [documentation site](https://jasonraimondi.githu
 pnpm add @jmondi/oauth2-server
 ```
 
+| Version | Latest Version | Security Updates |
+|---------|----------------|------------------|
+| 3.x     | :tada:         | :tada:           |
+| 2.x     |                | :tada:           |
+| 1.x     |                |                  |
+
 ### Endpoints 
 
 The server uses two endpoints, `GET /authorize` and `POST /token`. 
@@ -391,7 +397,7 @@ Please look at these great resources:
 - VIDEO: [What's Going On with the Implicit Flow?](https://www.youtube.com/watch?v=CHzERullHe8) by Aaron Parecki
 - [Is the OAuth 2.0 Implicit Flow Dead?](https://developer.okta.com/blog/2019/05/01/is-the-oauth-implicit-flow-dead) by Aaron Parecki (developer.okta.com)
 
-## Revoke Tokens (RFC7009 “OAuth 2.0 Token Revocation”)
+## Revoke Token
 
 Note: Implementing this endpoint is optional.
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -2,9 +2,11 @@
 
 ## Supported Versions
 
-| Version | Supported          |
-| ------- | ------------------ |
-| 2.x     | :white_check_mark: |
+| Version | Latest Version     | Security Updates   |
+|---------|--------------------|--------------------|
+| 3.x     | :white_check_mark: | :white_check_mark: |
+| 2.x     |                    | :white_check_mark: |
+| 1.x     |                    |                    |
 
 ## Reporting a Vulnerability
 

diff --git a/docs/configuration/index.md b/docs/configuration/index.md
@@ -13,15 +13,16 @@ type AuthorizationServerOptions = {
   requiresPKCE: true;
   requiresS256: false;
   notBeforeLeeway: 0;
-  tokenCID: "id"|"name"; // in 3.x default is "id", in 2.x the default is "name"
+  tokenCID: "id" | "name";
 }
 ```
 
-* `requiresPKCE` - Enabled by default, PKCE is enabled and encouraged for all users. If you need to support a legacy client system without PKCE, you can disable PKCE with the authorization server.
-* `requiresS256` - Disabled by default. If you want to require all clients to use S256, you can enable that here.
-* `notBeforeLeeway` - Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew.  Its value MUST be a number containing a NumericDate value.
-* `tokenCID` - Sets the JWT `accessToken.cid` to either the `client.id` or `client.name`. In 3.x the default is 
-  **"id"**, in v2.x the default was **"name"**. [(additional context)](https://github.com/jasonraimondi/ts-oauth2-server/blob/e7a31b207701f90552abc82d82c72b143bc15130/src/grants/abstract/abstract.grant.ts#L123)
+| Option            | Number         | Default | Details                                                                                                                                                                        |
+|-------------------|----------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `requiresPKCE`    | boolean        | true    | PKCE is enabled by default and recommended for all users. To support a legacy client without PKCE, disable this option. [[Learn more]][requires-pkce]                          |
+| `requiresS256`    | boolean        | true    | Disabled by default. If you want to require all clients to use S256, you can enable that here. [[Learn more]][requires-s256]                                                   |
+| `notBeforeLeeway` | number         | 0       | Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew.  Its value MUST be a number containing a NumericDate value.     |
+| `tokenCID`        | "id" or "name" | "id"    | Sets the JWT `accessToken.cid` to either the `client.id` or `client.name`.<br /><br />In 3.x the default is **"id"**, in v2.x the default was **"name"**. [[Learn more]][token-cid] |
 
 To configure these options, pass the value in as the last argument:
 
@@ -32,7 +33,11 @@ const authorizationServer = new AuthorizationServer(
   scopeRepository,
   new JwtService("secret-key"),
   {
-    requiresS256: true, // default is false
+    requiresS256: true,
   }
 );
 ```
+
+[requires-pkce]: https://datatracker.ietf.org/doc/html/rfc7636
+[requires-s256]: https://datatracker.ietf.org/doc/html/rfc7636#section-4.2
+[token-cid]: https://github.com/jasonraimondi/ts-oauth2-server/blob/e7a31b207701f90552abc82d82c72b143bc15130/src/grants/abstract/abstract.grant.ts#L123
diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md
@@ -111,10 +111,10 @@ app.get("/authorize", async (req: Express.Request, res: Express.Response) => {
 });
 ```
 
-## Revoke Tokens (RFC7009 “OAuth 2.0 Token Revocation”)
+## Revoke Token
 
 ::: tip Note 
-Implementing this endpoint is optional, but recommended.
+Implementing this endpoint is optional, but recommended. RFC7009 “OAuth 2.0 Token Revocation”
 :::
 
 The `/token/revoke` endpoint is a back channel endpoint that revokes an existing token.

diff --git a/docs/migration/v2_to_v3.md b/docs/migration/v2_to_v3.md
@@ -1,37 +1,35 @@
 # Migrating from v2 to v3
 
-_Estimated Upgrade Time: already ESM? 5 minutes; not ESM? it depends_
+Upgrade Time Estimate: ESM? 5 minutes; non-ESM? Varies
 
 [[toc]]
 
 ## This package is now pure ESM
 
-This package has been updated to a pure ESM (ECMAScript Modules) package. For more information on the implications of this change, refer to [Sindre Sorhus's writeup](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
+The package is now entirely ESM (ECMAScript Modules). More details about this change can be found in [Sindre Sorhus's writeup](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
 
+## `AuthorizationServer` Updates {#authorization-server}
 
-## AuthorizationServer {#authorization-server}
+In v2.x, `AuthorizationServer` constructor required all repositories. In v3.x, it has been simplified.
 
-In the previous version (v2.x), the `AuthorizationServer` constructor required all repositories. In version 3.x, the 
-constructor has been updated to simplify the defaults.
-
-Before
+**Before (v2.x):**
 
 ```typescript
 const authorizationServer = new AuthorizationServer(
-  authCodeRepository,    // not included in v3.x
+  authCodeRepository,
   clientRepository,
   accessTokenRepository,
   scopeRepository,
-  userRepository,        // not included in v3.x
+  userRepository,
   jwtService,
   {
-    requiresS256: false, // Default value in v2.x
-    tokenCID: "name",    // Default value in v2.x
+    requiresS256: false, 
+    tokenCID: "name",
   }
 );
 ```
 
-After
+**After (v3.x):**
 
 ```typescript
 const authorizationServer = new AuthorizationServer(
@@ -40,27 +38,27 @@ const authorizationServer = new AuthorizationServer(
   scopeRepository,
   new JwtService("secret-key"),
   {
-    requiresS256: true,  // Default value in v3.x
-    tokenCID: "id",      // Default value in v3.x
+    requiresS256: true,  
+    tokenCID: "id",
   }
 );
 ```
 
 ## Enabling Grants
 
-In version 3, the enableGrantType has been changed for the **"authorization_code"** and **"password"** grants.
+In v3, `enableGrantType` has been updated for the **"authorization_code"** and **"password"** grants.
 
 ### Authorization Code Grant
 
-To enable the AuthorizationCodeGrant, you now need to provide a [AuthorizationCodeRepository](../repositories/index.md#authorization-code-repository) and a [UserRepository](../repositories/index.md#user-repository).
+`AuthorizationCodeGrant` now requires a [AuthorizationCodeRepository](../repositories/index.md#authorization-code-repository) and a [UserRepository](../repositories/index.md#user-repository).
 
-**Before**
+**Before (v2.x):**
 
 ```typescript
 authorizationServer.enableGrantType("authorization_code");
 ```
 
-**After**
+**After (v3.x):**
 
 ```typescript
 authorizationServer.enableGrantType({
@@ -72,15 +70,15 @@ authorizationServer.enableGrantType({
 
 ### Password Grant
 
-To enable the PasswordGrant, you now need to provide a [UserRepository](../repositories/index.md#user-repository).
+`PasswordGrant` now requires a [UserRepository](../repositories/index.md#user-repository).
 
-**Before**
+**Before (v2.x):**
 
 ```typescript
 authorizationServer.enableGrantType("password");
 ```
 
-**After**
+**After (v3.x):**
 
 ```typescript
 authorizationServer.enableGrantType({
@@ -89,19 +87,19 @@ authorizationServer.enableGrantType({
 });
 ```
 
-## AuthorizationServerOptions default configuration that has been updated
+## `AuthorizationServerOptions` Default Configuration Updates
 
-The default configuration options for `AuthorizationServer` have been modified to align more strictly with the OAuth 2.0 specification:
+The default options for `AuthorizationServer` have been modified to better align with the OAuth 2.0 specification:
 
-| Option       | Old Value | New Value |
-|--------------| --------- | --------- |
-| requiresS256 | false     | true      |
-| tokenCID     | "name"    | "id"      |
+| Option       | v2.x Value | v3.x Value |
+|--------------|------------|------------|
+| requiresS256 | false      | true       |
+| tokenCID     | "name"     | "id"       |
 
-## AuthorizationServer.setOptions has been dropped
+## Removed `setOptions` Method
 
-If you happened to use this undocumented, public method, it has been dropped in v3. Options can be set on initialization of the AuthoriztionServer.
+The undocumented, public method `setOptions` has been removed in v3. Options can be set during `AuthorizationServer` initialization.
 
-## Updated `generateRandomToken` function
+## `generateRandomToken` Function Fix
 
-In version 3.x, a bug with the `generateRandomToken` function has been fixed.
+A bug in the `generateRandomToken` function has been fixed in v3.x.
diff --git a/docs/repositories/index.md b/docs/repositories/index.md
@@ -2,6 +2,8 @@
 
 ## Auth Code Repository
 
+OAuthAuthCodeRepository interface is utilized for managing OAuth authorization codes. It contains methods for retrieving an authorization code entity by its identifier, issuing a new authorization code, persisting an authorization code in the storage, checking if an authorization code has been revoked, and revoking an authorization code.
+
 ```typescript
 interface OAuthAuthCodeRepository {
 
@@ -30,6 +32,8 @@ interface OAuthAuthCodeRepository {
 
 ## Client Repository
 
+OAuthClientRepository interface is used for managing OAuth clients. It includes methods for fetching a client entity from storage by the client ID and for validating the client using the grant type and client secret.
+
 ```typescript
 interface OAuthClientRepository {
   // Fetch client entity from storage by client_id
@@ -46,6 +50,8 @@ interface OAuthClientRepository {
 
 ## Scope Repository
 
+The OAuthScopeRepository interface handles scope management. It defines methods for finding all scopes by their names and for finalizing the scopes. In the finalization, additional scopes can be added or removed after they've been validated against the client scopes.
+
 ```typescript
 interface OAuthScopeRepository {
   // Find all scopes by scope names
@@ -66,6 +72,8 @@ interface OAuthScopeRepository {
 
 ## Token Repository
 
+OAuthTokenRepository interface manages OAuth tokens. It contains methods for issuing a new token, persisting a token in the storage, issuing a refresh token, revoking tokens, and fetching a refresh token entity by the refresh token.
+
 ```typescript
 interface OAuthTokenRepository {
   // An async call that should return an OAuthToken that has not been 
@@ -108,6 +116,8 @@ interface OAuthTokenRepository {
 
 ## User Repository
 
+The OAuthUserRepository interface handles user management. It defines methods for fetching a user entity from storage by their credentials and optional grant type and client. This may involve validating the user's credentials.
+
 ```typescript
 interface OAuthUserRepository {