Added TypeScript typings (#122)

* Added typings for TS

* Including the types folder

* JWKS cache can use async methods

* Updated as requested

Co-authored-by: Steve Hobbs <steve.hobbs@auth0.com>

package.json

@@ -6,9 +6,11 @@
   "umd:main": "build/idtoken-verifier.umd.js",
   "module": "build/idtoken-verifier.esm.js",
   "source": "src/index.js",
+  "types": "types/index.d.ts",
   "files": [
     "build",
-    "src"
+    "src",
+    "types"
   ],
   "scripts": {
     "start": "gulp dev",

types/index.d.ts

@@ -0,0 +1,149 @@
+export default IdTokenVerifier;
+
+export interface JWK {
+  modulus: string;
+  exp: string;
+}
+
+/**
+ * Generic that indicates that the value can be a generic type T
+ * or a Promise that resolves with T
+ */
+type PromiseOrSync<T> = T | Promise<T>;
+
+/**
+ * Interface for a JWK cache.
+ * Can use a Map object.
+ */
+export interface JWKSCache {
+  get(key: string): PromiseOrSync<JWK | undefined>;
+  has(key: string): PromiseOrSync<boolean>;
+  set(key: string, value: JWK): PromiseOrSync<this>;
+}
+
+/**
+ * Callback used to notify the results of the validation asynchronously
+ * @param err error returned if the verify cannot be performed
+ * @param payload payload returned if the token is valid
+ */
+export type verifyCallback = (err: Error | null, payload: object | null) => any;
+
+/**
+ * Object containing the decoded token.
+ */
+export type DecodedToken = {
+  /**
+   * content of the JWT header
+   */
+  header: any;
+
+  /**
+   * token claims
+   */
+  payload: any;
+
+  /**
+   * encoded parts of the token
+   */
+  encoded: {
+    header: string;
+    payload: string;
+    signature: string;
+  };
+};
+
+export type validateAccessTokenCallback = (err?: Error) => any;
+
+export type IdTokenVerifierParameters = {
+  /**
+   * Name of the issuer of the token that should match the `iss`
+   * claim in the id_token
+   */
+  issuer: string;
+  /**
+   * Identifies the recipients that the JWT is intended for and should
+   * match the `aud` claim
+   */
+  audience: string;
+  /**
+   * Cache for JSON Web Token Keys; by default it has no cache
+   */
+  jwksCache?: JWKSCache;
+  /**
+   * A valid, direct URI to fetch the JSON Web Key Set (JWKS).
+   * Defaults to `${id_token.iss}/.well-known/jwks.json`
+   */
+  jwksURI?: string;
+  /**
+   * Algorithm in which the id_token was signed and will be
+   * used to validate
+   */
+  expectedAlg?: 'RS256';
+  /**
+   * Number of seconds that the clock can be out of sync
+   * while validating expiration of the id_token
+   */
+  leeway?: number;
+  /**
+   * Max age
+   */
+  maxAge?: number;
+};
+
+declare function IdTokenVerifier(parameters: IdTokenVerifierParameters): void;
+
+declare class IdTokenVerifier {
+  /**
+   * Creates a new id_token verifier
+   */
+  constructor(parameters: IdTokenVerifierParameters);
+
+  jwksCache: JWKSCache;
+  expectedAlg: string;
+  issuer: string;
+  audience: string;
+  leeway: number;
+  jwksURI: string;
+  maxAge: number;
+
+  /**
+   * Verifies an id_token
+   *
+   * It will validate:
+   * - signature according to the algorithm configured in the verifier.
+   * - if nonce is present and matches the one provided
+   * - if `iss` and `aud` claims matches the configured issuer and audience
+   * - if token is not expired and valid (if the `nbf` claim is in the past)
+   * @param token id_token to verify
+   * @param requestedNonce nonce value that should match the one in the id_token claims
+   * @param cb callback used to notify the results of the validation
+   */
+  verify(token: string, requestedNonce: string, cb: verifyCallback): any;
+  verify(token: string, cb: verifyCallback): any;
+
+  /**
+   * Decodes a well formed JWT without any verification
+   * @param token decodes the token
+   * @returns token if it's valid according to `exp` and `nbf`
+   */
+  decode(token: string): DecodedToken;
+
+  /**
+   * Validates an access_token based on {@link http://openid.net/specs/openid-connect-core-1_0.html#ImplicitTokenValidation}.
+   * The id_token from where the alg and atHash parameters are taken,
+   * should be decoded and verified before using thisfunction
+   *
+   * @param access_token the access_token
+   * @param alg The algorithm defined in the header of the
+   * previously verified id_token under the "alg" claim.
+   * @param atHash The "at_hash" value included in the payload
+   * of the previously verified id_token.
+   * @param cb callback used to notify the results of the validation.
+   */
+  validateAccessToken(
+    accessToken: string,
+    alg: string,
+    atHash: string,
+    cb: validateAccessTokenCallback
+  ): void;
+}