From a1e975b8ac688e88dd3ffbfba625f955ccd82e26 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Sat, 20 Jun 2020 14:45:11 +0200
Subject: [PATCH] auth-backend: document identity types

---
 plugins/auth-backend/src/identity/types.ts | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/plugins/auth-backend/src/identity/types.ts b/plugins/auth-backend/src/identity/types.ts
index c19f8e1ddf..1ceb9dd2cb 100644
--- a/plugins/auth-backend/src/identity/types.ts
+++ b/plugins/auth-backend/src/identity/types.ts
@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+/** Represents any form of serializable JWK */
 export interface AnyJWK extends Record<string, string> {
   use: 'sig';
   alg: string;
@@ -21,18 +22,34 @@ export interface AnyJWK extends Record<string, string> {
   kty: string;
 }
 
+/** A KeyStore can store and keep track of recently used JWKs */
 export type KeyStore = {
+  /**
+   * Store a new key to be used for signing. Before the key has been successfully
+   * stored it should not be used for signing.
+   */
   storeKey(params: { key: AnyJWK }): Promise<void>;
 
+  /**
+   * List all keys that are currently being used to sign tokens, or have been used
+   * in the past within the token expiration time, including a grace period.
+   */
   listKeys(): Promise<{ keys: AnyJWK[] }>;
 };
 
+/** Parameters used to issue new ID Tokens */
 export type TokenParams = {
+  /** The claims that will be embedded within the token */
   claims: {
+    /** The token subject, i.e. User ID */
     sub: string;
   };
 };
 
+/** A TokenIssuer is able to issue verifiable ID Tokens on demand */
 export type TokenIssuer = {
+  /**
+   * Issues a new ID Token
+   */
   issueToken(params: TokenParams): Promise<string>;
 };