[KEYCLOAK-13841] Update typescript declarations for keycloak-nodejs-connect

Author: ckwalsh

keycloak.d.ts

@@ -32,21 +32,60 @@ declare namespace KeycloakConnect {
     cookies?: boolean
   }
 
-  interface GrantProperties {
-    access_token?: string
-    refresh_token?: string
-    id_token?: string
-    expires_in?: string
-    token_type?: string
+  interface Claims {
+    // In the future it may make sense to populate this with some known claims
+    [key: string]: any
+  }
+
+  interface EnforcerOptions {
+    response_mode?: 'permissions' | 'token'
+    resource_server_id?: string
+    claims?: Claims
+  }
+
+  interface Permission {
+    id: string
+    scopes?: string[]
+  }
+
+  interface AuthzRequest {
+    audience?: string
+    claim_token?: string
+    claim_token_format?: string
+    permissions: Permission[]
+  }
+  
+  interface AuthzRequestGrant extends AuthzRequest {
+    response_mode: undefined
+  }
+
+  interface AuthzRequestOther extends AuthzRequest {
+    response_mode: 'decision' | 'permissions'
+  }
+
+  interface TokenContent {
+    exp: number
   }
 
   interface Token {
+    clientId?: string
+    token?: string
+    content?: TokenContent
     isExpired(): boolean
     hasRole(roleName: string): boolean
     hasApplicationRole(appName: string, roleName: string): boolean
     hasRealmRole(roleName: string): boolean
   }
 
+  interface GrantProperties {
+    access_token?: Token
+    refresh_token?: Token
+    id_token?: Token
+    expires_in?: number
+    token_type?: string
+    __raw?: string
+  }
+
   interface GrantManager {
     /**
      * Use the direct grant API to obtain a grant from Keycloak.
@@ -280,7 +319,67 @@ declare namespace KeycloakConnect {
      *
      * @param {String} spec The protection spec (optional)
      */
-    protect(spec: GaurdFn|string): express.RequestHandler
+    protect(spec?: GaurdFn|string): express.RequestHandler
+    
+    /**
+     * Enforce access based on the given permissions. This method operates in two modes, depending on the `response_mode`
+     * defined for this policy enforcer.
+     *
+     * If `response_mode` is set to `token`, permissions are obtained using an specific grant type. As a consequence, the
+     * token with the permissions granted by the server is updated and made available to the application via `request.kauth.grant.access_token`.
+     * Use this mode when your application is using sessions and you want to cache previous decisions from the server, as well automatically handle
+     * refresh tokens. This mode is especially useful for applications acting as client and resource server.
+     *
+     * If `response_mode` is set to `permissions`, the server only returns the list of granted permissions (no oauth2 response).
+     * Previous decisions are not cached and the policy enforcer will query the server every time to get a decision.
+     * This is the default `response_mode`.
+     *
+     * You can set `response_mode` as follows:
+     *
+     *      keycloak.enforcer('item:read', {response_mode: 'token'})
+     *
+     * In all cases, if the request is already populated with a valid access token (for instance, bearer tokens sent by clients to the application),
+     * the policy enforcer will first try to resolve permissions from the current token before querying the server.
+     *
+     * By default, the policy enforcer will use the `client_id` defined to the application (for instance, via `keycloak.json`) to
+     * reference a client in Keycloak that supports Keycloak Authorization Services. In this case, the client can not be public given
+     * that it is actually a resource server.
+     *
+     * If your application is acting as a client and resource server, you can use the following configuration to specify the client
+     * in Keycloak with the authorization settings:
+     *
+     *      keycloak.enforcer('item:read', {resource_server_id: 'nodejs-apiserver'})
+     *
+     * It is recommended to use separated clients in Keycloak to represent your frontend and backend.
+     *
+     * If the application you are protecting is enabled with Keycloak authorization services and you have defined client credentials
+     * in `keycloak.json`, you can push additional claims to the server and make them available to your policies in order to make decisions.
+     * For that, you can define a `claims` configuration option which expects a `function` that returns a JSON with the claims you want to push:
+     *
+     *      app.get('/protected/resource', keycloak.enforcer(['resource:view', 'resource:write'], {
+              claims: function(request) {
+                return {
+                  "http.uri": ["/protected/resource"],
+                  "user.agent": // get user agent  from request
+                }
+              }
+            }), function (req, res) {
+              // access granted
+            });
+     *
+     * @param {String[]} expectedPermissions A single string representing a permission or an arrat of strings representing the permissions. For instance, 'item:read' or ['item:read', 'item:write'].
+     */
+    enforcer(expectedPermissions: string|string[], options?: EnforcerOptions): express.RequestHandler
+
+    /**
+     * Apply check SSO middleware to an application or specific URL.
+     *
+     * Check SSO will only authenticate the client if the user is already logged-in,
+     * if the user is not logged-in the browser will be redirected back
+     * to the originally-requested URL and remain unauthenticated.
+     *
+     */
+    checkSso(): express.RequestHandler
 
     /**
      * Callback made upon successful authentication of a user.
@@ -336,6 +435,9 @@ declare namespace KeycloakConnect {
 
     getGrantFromCode(code: string, req: express.Request, res: express.Response): Promise<Grant>
 
+    checkPermissions(authz_req: AuthzRequestGrant, req: express.Request, cb?: (grant: Grant) => void): Promise<Grant>
+    checkPermissions(authz_req: AuthzRequestOther, req: express.Request, cb?: (grant: Object) => void): Promise<Object>
+
     loginUrl(uuid: string, redirectUrl: string): string
 
     logoutUrl(redirectUrl: string): string