OIDC: document OidcError use (#3808)

* comments

* Update src/oidc/authorize.ts

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Update src/oidc/register.ts

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

---------

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

src/oidc/authorize.ts

@@ -198,7 +198,8 @@ const normalizeBearerTokenResponseTokenType = (response: SigninResponse): Bearer
  * @param code - authorization code as returned by OP during authorization
  * @param storedAuthorizationParams - stored params from start of oidc login flow
  * @returns valid bearer token response
- * @throws when request fails, or returned token response is invalid
+ * @throws An `Error` with `message` set to an entry in {@link OidcError},
+ *      when the request fails, or the returned token response is invalid.
  */
 export const completeAuthorizationCodeGrant = async (
     code: string,

src/oidc/error.ts

@@ -14,6 +14,10 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+/**
+ * Errors expected to be encountered during OIDC discovery, client registration, and authentication.
+ * Not intended to be displayed directly to the user.
+ */
 export enum OidcError {
     NotSupported = "OIDC authentication not supported",
     Misconfigured = "OIDC is misconfigured",

src/oidc/index.ts

@@ -14,4 +14,9 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+export * from "./authorize";
+export * from "./discovery";
+export * from "./error";
+export * from "./register";
 export * from "./tokenRefresher";
+export * from "./validate";

src/oidc/register.ts

@@ -34,7 +34,8 @@ export type OidcRegistrationClientMetadata = {
  * @param registrationEndpoint - URL as returned from issuer ./well-known/openid-configuration
  * @param clientMetadata - registration metadata
  * @returns resolves to the registered client id when registration is successful
- * @throws when registration request fails, or response is invalid
+ * @throws An `Error` with `message` set to an entry in {@link OidcError},
+ *      when the registration request fails, or the response is invalid.
  */
 const doRegistration = async (
     registrationEndpoint: string,