@magda/authentication-plugin-sdk 0.0.60-alpha.7 → 0.0.60-dt.1

package/README.md

@@ -15,9 +15,24 @@ You can use [this repo](https://github.com/magda-io/magda-auth-template) as [a t
  * @returns {Router}
  */
 export declare function createMagdaSessionRouter(
-    options: MagdaSessionRouterOptions
+  options: MagdaSessionRouterOptions
 ): Router;
 
+/**
+ * Complete destroy Magda session and remove session cookie from the user agent
+ *
+ * @export
+ * @param {Request} req
+ * @param {Response} res
+ * @param {SessionCookieOptions} cookieOptions
+ * @return {*}  {Promise<void>}
+ */
+export declare async function destroyMagdaSession(
+  req: Request,
+  res: Response,
+  cookieOptions: SessionCookieOptions
+): Promise<void>;
+
 /**
  * Verify the user using the user profile received during the authentication.
  * If a user can be located, return UserToken type data.
@@ -50,19 +65,19 @@ export declare function createMagdaSessionRouter(
  * @returns {Promise<UserToken>}
  */
 export declare function createOrGetUserToken(
-    authApi: AuthApiClient,
-    profile: passport.Profile,
-    source: string,
-    beforeUserCreated?: (
-        authApiClient: AuthApiClient,
-        userData: User,
-        profile: passport.Profile
-    ) => Promise<User>,
-    afterUserCreated?: (
-        authApiClient: AuthApiClient,
-        user: User,
-        profile: passport.Profile
-    ) => Promise<void>
+  authApi: AuthApiClient,
+  profile: passport.Profile,
+  source: string,
+  beforeUserCreated?: (
+    authApiClient: AuthApiClient,
+    userData: User,
+    profile: passport.Profile
+  ) => Promise<User>,
+  afterUserCreated?: (
+    authApiClient: AuthApiClient,
+    user: User,
+    profile: passport.Profile
+  ) => Promise<void>
 ): Promise<UserToken>;
 
 /**
@@ -75,23 +90,23 @@ export declare function createOrGetUserToken(
  * @returns
  */
 export declare function getAbsoluteUrl(
-    url: string,
-    baseUrl: string,
-    optionalQueries?: {
-        [key: string]: string;
-    }
+  url: string,
+  baseUrl: string,
+  optionalQueries?: {
+    [key: string]: string;
+  }
 ): string;
 
 export declare function redirectOnSuccess(
-    toURL: string,
-    req: Request,
-    res: Response
+  toURL: string,
+  req: Request,
+  res: Response
 ): void;
 
 export declare function redirectOnError(
-    err: any,
-    toURL: string,
-    req: Request,
-    res: Response
+  err: any,
+  toURL: string,
+  req: Request,
+  res: Response
 ): void;
 ```

package/dist/index.d.ts

@@ -1,122 +1,162 @@
-import { Router, Request, Response } from "express";
-import AuthApiClient, { User, UserToken } from "@magda/auth-api-client";
-import passport from "passport";
-declare global {
-    namespace Express {
-        /**
-         * This defines magda session data type.
-         * the default session data type is `UserToken` (i.e. only user id field is available and is a compulsory field)
-         * But any auth plugin provider could choose to customise the session by adding more fields (e.g. `arcgis`).
-         * We also make sure it allows extra fields here.
-         */
-        interface User extends UserToken {
-            [key: string]: any;
-        }
-    }
-}
-export declare type MagdaSessionRouterOptions = {
-    cookieOptions: SessionCookieOptions;
-    sessionSecret: string;
-    sessionDBHost: string;
-    sessionDBPort: number;
-    sessionDBUser?: string;
-    sessionDBPassword?: string;
-    sessionDBName?: string;
-};
-export declare type SessionCookieOptions = {
-    maxAge?: number;
-    signed?: boolean;
-    expires?: Date;
-    httpOnly?: boolean;
-    path?: string;
-    domain?: string;
-    secure?: boolean | "auto";
-    encode?: (val: string) => string;
-    sameSite?: boolean | "lax" | "strict" | "none";
-};
-export declare const DEFAULT_SESSION_COOKIE_NAME: string;
-export declare let DEFAULT_SESSION_COOKIE_OPTIONS: SessionCookieOptions;
-/**
- * Create an express router that can be used to enable session on an express application.
- *
- * @export
- * @param {MagdaSessionRouterOptions} options
- * @returns {Router}
- */
-export declare function createMagdaSessionRouter(options: MagdaSessionRouterOptions): Router;
-/**
- * Different type of AuthenticationMethod:
- * - IDP-URI-REDIRECTION: the plugin will rediredct user agent to idp (identity provider) for authentication. e.g. Google & fackebook oauth etc.
- *   - This is the default method.
- * - PASSWORD: the plugin expect frontend do a form post that contains username & password to the plugin for authentication
- * - QR-CODE: the plugin offers a url that is used by the frontend to request auth challenge data. The data will be encoded into a QR-code image and expect the user scan the QR code with a mobile app to complete the authentication request.
- *   - Once the QR-code image is generated, the frontend is expected to start polling a pre-defined plugin url to check whether the authentication is complete or not.
- */
-export declare type AuthenticationMethod = "IDP-URI-REDIRECTION" | "PASSWORD" | "QR-CODE";
-export interface AuthPluginConfig extends Omit<AuthPluginBasicConfig, "baseUrl"> {
-    name: string;
-    iconUrl: string;
-    authenticationMethod: AuthenticationMethod;
-    loginFormExtraInfoHeading?: string;
-    loginFormExtraInfoContent?: string;
-    loginFormUsernameFieldLabel?: string;
-    loginFormPasswordFieldLabel?: string;
-    qrCodeImgDataRequestUrl?: string;
-    qrCodeAuthResultPollUrl?: string;
-    qrCodeExtraInfoHeading?: string;
-    qrCodeExtraInfoContent?: string;
-}
-/**
- * Basic Auth Plugin are the config info that supplied to Gateway
- * via [authPlugins](https://github.com/magda-io/magda/tree/master/deploy/helm/internal-charts/gateway) helm chart config
- */
-export declare type AuthPluginBasicConfig = {
-    key: string;
-    baseUrl: string;
-};
-/**
- * Join `url` with `baseUrl` if `url` is not an absolute url
- *
- * @export
- * @param {string} url
- * @param {string} baseUrl
- * @param {{ [key: string]: string }} [optionalQueries]
- * @returns
- */
-export declare function getAbsoluteUrl(url: string, baseUrl: string, optionalQueries?: {
-    [key: string]: string;
-}): string;
-export declare function redirectOnSuccess(toURL: string, req: Request, res: Response): void;
-export declare function redirectOnError(err: any, toURL: string, req: Request, res: Response): void;
-/**
- * Verify the user using the user profile received during the authentication.
- * If a user can be located, return UserToken type data.
- * Otherwise, create a new user and return UserToken type data .
- *
- * @export
- * @param {AuthApiClient} authApi
- * @param {passport.Profile} profile
- * @param {string} source
- * @param {(
- *         authApiClient: AuthApiClient,
- *         userData: User,
- *         profile: passport.Profile
- *     ) => Promise<User>} [beforeUserCreated] an optional handler that will be called just before a user is created.
- * The user data returned by this handler will be used to create the user record. The following parameters will be provided to the handler:
- * - authApiClient: Auth API Client. You can use it to add a role to the user.
- * - userData: the user data that is converted from the user profile received using the default conversion logic.
- * - profile: the user profile received
- *
- * @param {(
- *         authApiClient: AuthApiClient,
- *         user: User,
- *         profile: passport.Profile
- *     ) => Promise<void>} [afterUserCreated] an optional call that will be called when a user has just been created.
- * The following parameters will be provided to the handler:
- * - authApiClient: Auth API Client. You can use it to add a role to the user.
- * - user: the user data of the magda user that is just created.
- * - profile: the user profile received
- *
- * @returns {Promise<UserToken>}
- */
-export declare function createOrGetUserToken(authApi: AuthApiClient, profile: passport.Profile, source: string, beforeUserCreated?: (authApiClient: AuthApiClient, userData: User, profile: passport.Profile) => Promise<User>, afterUserCreated?: (authApiClient: AuthApiClient, user: User, profile: passport.Profile) => Promise<void>): Promise<UserToken>;
+import AuthApiClient from '@magda/auth-api-client';
+import express from 'express';
+import passport from 'passport';
+import { Request as Request_2 } from 'express';
+import { Response as Response_2 } from 'express';
+import { Router } from 'express';
+import { User } from '@magda/auth-api-client';
+import { UserToken } from '@magda/auth-api-client';
+
+/**
+ * Different type of AuthenticationMethod:
+ * - IDP-URI-REDIRECTION: the plugin will rediredct user agent to idp (identity provider) for authentication. e.g. Google & fackebook oauth etc.
+ *   - This is the default method.
+ * - PASSWORD: the plugin expect frontend do a form post that contains username & password to the plugin for authentication
+ * - QR-CODE: the plugin offers a url that is used by the frontend to request auth challenge data. The data will be encoded into a QR-code image and expect the user scan the QR code with a mobile app to complete the authentication request.
+ *   - Once the QR-code image is generated, the frontend is expected to start polling a pre-defined plugin url to check whether the authentication is complete or not.
+ */
+export declare type AuthenticationMethod = "IDP-URI-REDIRECTION" | "PASSWORD" | "QR-CODE";
+
+/**
+ * Basic Auth Plugin are the config info that supplied to Gateway
+ * via [authPlugins](https://github.com/magda-io/magda/tree/master/deploy/helm/internal-charts/gateway) helm chart config
+ */
+export declare type AuthPluginBasicConfig = {
+    key: string;
+    baseUrl: string;
+};
+
+export declare interface AuthPluginConfig extends Omit<AuthPluginBasicConfig, "baseUrl"> {
+    name: string;
+    iconUrl: string;
+    authenticationMethod: AuthenticationMethod;
+    loginFormExtraInfoHeading?: string;
+    loginFormExtraInfoContent?: string;
+    loginFormUsernameFieldLabel?: string;
+    loginFormPasswordFieldLabel?: string;
+    qrCodeImgDataRequestUrl?: string;
+    qrCodeAuthResultPollUrl?: string;
+    qrCodeExtraInfoHeading?: string;
+    qrCodeExtraInfoContent?: string;
+}
+
+export declare type CookieOptions = CookieOptions_2;
+
+/** This is present in the express-session types but not actually exported properly, so it needs to be copy-pasted here */
+declare type CookieOptions_2 = {
+    maxAge?: number;
+    signed?: boolean;
+    expires?: Date;
+    httpOnly?: boolean;
+    path?: string;
+    domain?: string;
+    secure?: boolean | "auto";
+    encode?: (val: string) => string;
+    sameSite?: boolean | "lax" | "strict" | "none";
+};
+
+/**
+ * Create an express router that can be used to enable session on an express application.
+ *
+ * @export
+ * @param {MagdaSessionRouterOptions} options
+ * @returns {Router}
+ */
+export declare function createMagdaSessionRouter(options: MagdaSessionRouterOptions): Router;
+
+/**
+ * Verify the user using the user profile received during the authentication.
+ * If a user can be located, return UserToken type data.
+ * Otherwise, create a new user and return UserToken type data .
+ *
+ * @export
+ * @param {AuthApiClient} authApi
+ * @param {passport.Profile} profile
+ * @param {string} source
+ * @param {(
+ *         authApiClient: AuthApiClient,
+ *         userData: User,
+ *         profile: passport.Profile
+ *     ) => Promise<User>} [beforeUserCreated] an optional handler that will be called just before a user is created.
+ * The user data returned by this handler will be used to create the user record. The following parameters will be provided to the handler:
+ * - authApiClient: Auth API Client. You can use it to add a role to the user.
+ * - userData: the user data that is converted from the user profile received using the default conversion logic.
+ * - profile: the user profile received
+ *
+ * @param {(
+ *         authApiClient: AuthApiClient,
+ *         user: User,
+ *         profile: passport.Profile
+ *     ) => Promise<void>} [afterUserCreated] an optional call that will be called when a user has just been created.
+ * The following parameters will be provided to the handler:
+ * - authApiClient: Auth API Client. You can use it to add a role to the user.
+ * - user: the user data of the magda user that is just created.
+ * - profile: the user profile received
+ *
+ * @returns {Promise<UserToken>}
+ */
+export declare function createOrGetUserToken(authApi: AuthApiClient, profile: passport.Profile, source: string, beforeUserCreated?: (authApiClient: AuthApiClient, userData: User, profile: passport.Profile) => Promise<User>, afterUserCreated?: (authApiClient: AuthApiClient, user: User, profile: passport.Profile) => Promise<void>): Promise<UserToken>;
+
+export declare const DEFAULT_SESSION_COOKIE_NAME: string;
+
+export declare const DEFAULT_SESSION_COOKIE_OPTIONS: CookieOptions_2;
+
+export declare const deleteCookie: typeof deleteCookie_2;
+
+declare function deleteCookie_2(cookieName: string, cookieOptions: CookieOptions_2, res: express.Response): void;
+
+/**
+ * Complete destroy Magda session and remove session cookie from the user agent
+ *
+ * @export
+ * @param {Request} req
+ * @param {Response} res
+ * @param {SessionCookieOptions} cookieOptions
+ * @return {*}  {Promise<void>}
+ */
+export declare function destroyMagdaSession(req: Request_2, res: Response_2, cookieOptions: SessionCookieOptions): Promise<void>;
+
+export declare const destroySession: typeof destroySession_2;
+
+/**
+ * destroy the session.
+ *  - will delete the session data from session store only.
+ *  - will not delete session cookie (Call deleteCookie method for deleting cookie)
+ * @export
+ * @param {express.Request} req
+ * @return {*}  {Promise<void>}
+ */
+declare function destroySession_2(req: express.Request): Promise<void>;
+
+/**
+ * Join `url` with `baseUrl` if `url` is not an absolute url
+ *
+ * @export
+ * @param {string} url
+ * @param {string} baseUrl
+ * @param {{ [key: string]: string }} [optionalQueries]
+ * @returns
+ */
+export declare function getAbsoluteUrl(url: string, baseUrl: string, optionalQueries?: {
+    [key: string]: string;
+}): string;
+
+export declare function getSessionId(req: express.Request, secret?: string): string;
+
+export declare type MagdaSessionRouterOptions = {
+    cookieOptions: SessionCookieOptions;
+    sessionSecret: string;
+    sessionDBHost: string;
+    sessionDBPort: number;
+    sessionDBUser?: string;
+    sessionDBPassword?: string;
+    sessionDBName?: string;
+};
+
+export declare function redirectOnError(err: any, toURL: string, req: Request_2, res: Response_2): void;
+
+export declare function redirectOnSuccess(toURL: string, req: Request_2, res: Response_2): void;
+
+export declare type SessionCookieOptions = CookieOptions_2;
+
+export { }