@jitar-plugins/authentication 0.0.1

package/README.md

@@ -0,0 +1,178 @@
+
+# Authentication | Jitar Plugins
+
+This package provides plugins for integrating the [The Shelf authentication package](https://github.com/MaskingTechnology/theshelf/tree/main/packages/authentication) in Jitar applications.
+
+It contains two types of middleware:
+
+* **Authentication** - server side authentication handling.
+* **Requester** - client side authentication handling.
+
+Both are required for the integration.
+
+## Installation
+
+```bash
+npm install @theshelf/authentication @jitar-plugins/authentication @jitar-plugins/http
+```
+
+## Usage
+
+Follow the following steps to configure and use the provided plugins.
+
+### Step 1 - Configure the middleware
+
+Both types of middleware need to be instantiated with configuration.
+
+The authentication middleware operates on the server side and handles the actual authentication.
+
+```ts
+// src/middleware/authenticationMiddleware.ts
+
+import identityProvider from '@theshelf/authentication';
+import { AuthenticationMiddleware } from '@jitar-plugins/authentication';
+
+// FQNs to the auth handling procedures
+const authProcedures = {
+    loginUrl: 'domain/authentication/getLoginUrl',
+    login: 'domain/authentication/login',
+    logout: 'domain/authentication/logout'
+};
+
+// The client path to return to after a succesful login
+const redirectPath = '/afterlogin';
+
+const whiteList: string[] = [
+    // List of public FQNs
+];
+
+export default new AuthenticationMiddleware(identityProvider, authProcedures, redirectPath, whiteList);
+```
+
+The requester middleware operates on the client side (web browser) and provides auth informations with every request.
+
+```ts
+// src/middleware/requesterMiddleware.ts
+
+import { RequesterMiddleware } from '@jitar-plugins/authentication';
+
+// The server provides a session key after login that needs to be captured.
+const key = new URLSearchParams(globalThis.location?.search).get('key');
+const authorization = key !== undefined ? `Bearer ${key}` : undefined;
+
+export default new RequesterMiddleware(authorization);
+```
+
+To make sure the client redirects to the original location after login, we also need a third middleware comming from the http package.
+
+```ts
+// src/middleware/originMiddleware.ts
+
+import OriginMiddleware from '@jitar-plugins/http';
+
+export default new OriginMiddleware();
+```
+
+### Step 2 - Activate the middleware
+
+With the middleware in place, the need to be activated.
+
+For the server side, this means adding the authentication middleware to the service configuration.
+This is most likily the proxy / standalone service.
+
+```json
+/* services/proxy.json */
+{
+    "url": "http://example.com:3000",
+    "middleware": [ /* add middleware here, in this order */
+        "./middleware/originMiddleware",
+        "./middleware/authenticationMiddleware"
+    ],
+    "proxy":
+    {
+        /* service configuration */
+    }
+}
+```
+
+On the client side, it needs to be added to the Vite configuration.
+
+```ts
+// vite.config.ts
+
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import jitar from '@jitar/plugin-vite';
+
+export default defineConfig({
+  build: {
+    emptyOutDir: false
+  },
+  plugins: [
+    react(),
+    jitar({
+      sourceDir: 'src',
+      targetDir: 'dist',
+      jitarDir: 'domain',
+      jitarUrl: 'http://localhost:3000',
+      segments: [],
+      middleware: [ './middleware/requesterMiddleware' ] // Add middleware here
+    })
+  ]
+});
+```
+
+### Step 3 - Implement the auth procedures
+
+The authentication middleware refers to three procedures that need to be implemented in the application.
+
+```ts
+// src/domain/authentication/getLoginUrl'.ts
+
+export default async function getLoginUrl(): Promise<string>
+{
+    // The authentication middleware will provide the login url.
+    return '';
+}
+```
+
+```ts
+// src/domain/authentication/login'.ts
+
+export default async function login(identity: Identity): Promise<Requester>
+{
+    // Get the requester data from the given identity.
+}
+```
+
+```ts
+// src/domain/authentication/logout'.ts
+
+export default async function logout(): Promise<void>
+{
+    // The authentication middleware will handle the logout.
+    // Implementent additional logic here.
+}
+```
+
+### Step 4 - Expose the auth procedures
+
+The procedures need to be exposed publicly to make them acessible.
+
+```json
+{
+    "./domain/authentication/getLoginUrl": { "default": {  "access": "public" } },
+    "./domain/authentication/login": { "default": {  "access": "public" } },
+    "./domain/authentication/logout": { "default": {  "access": "public" } }
+}
+```
+
+### Step 5 - Implement the client redirect path
+
+This path will be called after a succesful login with the session key.
+
+```http
+GET http://app.example.com/afterlogin?key=XXXXXX
+```
+
+The requester middleware grabs and stores the key, the app can ignore it.

package/dist/AuthenticationMiddleware.d.ts

@@ -0,0 +1,14 @@
+import type { Middleware, NextHandler, Request } from 'jitar';
+import { Response } from 'jitar';
+import type { IdentityProvider } from '@theshelf/authentication';
+type AuthProcedures = {
+    loginUrl: string;
+    login: string;
+    logout: string;
+};
+export default class AuthenticationMiddleware implements Middleware {
+    #private;
+    constructor(identityProvider: IdentityProvider, authProcedures: AuthProcedures, redirectPath: string, whiteList: string[]);
+    handle(request: Request, next: NextHandler): Promise<Response>;
+}
+export {};

package/dist/AuthenticationMiddleware.js

@@ -0,0 +1,146 @@
+import { Response, Unauthorized } from 'jitar';
+import crypto from 'node:crypto';
+const IDENTITY_PARAMETER = 'identity';
+const REQUESTER_PARAMETER = '*requester';
+const JITAR_TRUST_HEADER_KEY = 'X-Jitar-Trust-Key';
+const sessions = new Map();
+export default class AuthenticationMiddleware {
+    #identityProvider;
+    #authProcedures;
+    #redirectPath;
+    #whiteList;
+    constructor(identityProvider, authProcedures, redirectPath, whiteList) {
+        this.#identityProvider = identityProvider;
+        this.#authProcedures = authProcedures;
+        this.#redirectPath = redirectPath;
+        this.#whiteList = whiteList;
+    }
+    async handle(request, next) {
+        if (request.hasHeader(JITAR_TRUST_HEADER_KEY)) {
+            return next();
+        }
+        switch (request.fqn) {
+            case this.#authProcedures.loginUrl: return this.#getLoginUrl(request);
+            case this.#authProcedures.login: return this.#createSession(request, next);
+            case this.#authProcedures.logout: return this.#destroySession(request, next);
+            default: return this.#handleRequest(request, next);
+        }
+    }
+    async #getLoginUrl(request) {
+        const origin = this.#getOrigin(request);
+        const url = await this.#identityProvider.getLoginUrl(origin);
+        return new Response(200, url);
+    }
+    async #createSession(request, next) {
+        const data = Object.fromEntries(request.args);
+        const origin = this.#getOrigin(request);
+        const session = await this.#identityProvider.login(origin, data);
+        request.args.clear();
+        request.setArgument(IDENTITY_PARAMETER, session.identity);
+        const response = await next();
+        if (response.status !== 200) {
+            await this.#identityProvider.logout(session);
+            return response;
+        }
+        session.key = this.#generateKey();
+        session.requester = response.result;
+        sessions.set(session.key, session);
+        this.#setAuthorizationHeader(response, session);
+        this.#setRedirectHeader(response, session.key, origin);
+        return response;
+    }
+    async #destroySession(request, next) {
+        const key = this.#extractAuthorizationKey(request);
+        if (key === undefined) {
+            throw new Unauthorized('Invalid authorization key');
+        }
+        const session = this.#getSession(key);
+        await this.#identityProvider.logout(session);
+        sessions.delete(key);
+        return next();
+    }
+    async #handleRequest(request, next) {
+        const storedSession = this.#authorize(request);
+        if (storedSession === undefined) {
+            return next();
+        }
+        const activeSession = this.#isSessionExpired(storedSession)
+            ? await this.#refreshSession(storedSession)
+            : storedSession;
+        request.setArgument(REQUESTER_PARAMETER, activeSession.requester);
+        const response = await next();
+        if (activeSession !== storedSession) {
+            this.#setAuthorizationHeader(response, activeSession);
+        }
+        return response;
+    }
+    #authorize(request) {
+        const key = this.#extractAuthorizationKey(request);
+        return key === undefined
+            ? this.#authorizePublic(request.fqn)
+            : this.#authorizeProtected(key);
+    }
+    #authorizePublic(fqn) {
+        if (this.#whiteList.includes(fqn)) {
+            return;
+        }
+        throw new Unauthorized('Not a public resource');
+    }
+    #authorizeProtected(key) {
+        return this.#getSession(key);
+    }
+    #getSession(key) {
+        const session = sessions.get(key);
+        if (session === undefined) {
+            throw new Unauthorized('Invalid authorization key');
+        }
+        return session;
+    }
+    #isSessionExpired(session) {
+        const now = new Date();
+        return session.expires < now;
+    }
+    async #refreshSession(session) {
+        try {
+            const newSession = await this.#identityProvider.refresh(session);
+            newSession.key = this.#generateKey();
+            sessions.delete(session.key);
+            sessions.set(newSession.key, newSession);
+            return newSession;
+        }
+        catch {
+            throw new Unauthorized('Session expired');
+        }
+    }
+    #extractAuthorizationKey(request) {
+        const authorization = this.#getAuthorizationHeader(request);
+        if (authorization === undefined) {
+            return;
+        }
+        const [type, key] = authorization.split(' ');
+        if (type.toLowerCase() !== 'bearer') {
+            throw new Unauthorized('Invalid authorization type');
+        }
+        return key;
+    }
+    #getAuthorizationHeader(request) {
+        return request.getHeader('Authorization');
+    }
+    #setAuthorizationHeader(response, session) {
+        response.setHeader('Authorization', `Bearer ${session.key}`);
+    }
+    #setRedirectHeader(response, key, origin) {
+        response.setHeader('Location', new URL(`${this.#redirectPath}?key=${key}`, origin).href);
+    }
+    #getOrigin(request) {
+        return request.getHeader('origin');
+    }
+    #generateKey() {
+        const id1 = crypto.randomUUID();
+        const id2 = crypto.randomUUID();
+        const id3 = crypto.randomUUID();
+        const id4 = crypto.randomUUID();
+        const input = id1 + id2 + id3 + id4;
+        return crypto.createHash('sha512').update(input, 'utf8').digest('hex');
+    }
+}

package/dist/RequesterMiddleware.d.ts

@@ -0,0 +1,6 @@
+import type { Middleware, NextHandler, Request, Response } from 'jitar';
+export default class RequesterMiddleware implements Middleware {
+    #private;
+    constructor(authorization?: string);
+    handle(request: Request, next: NextHandler): Promise<Response>;
+}

package/dist/RequesterMiddleware.js

@@ -0,0 +1,24 @@
+export default class RequesterMiddleware {
+    #authorization;
+    constructor(authorization) {
+        this.#authorization = authorization;
+    }
+    async handle(request, next) {
+        if (this.#authorization !== undefined) {
+            request.setHeader('Authorization', this.#authorization);
+        }
+        try {
+            const response = await next();
+            if (response.hasHeader('Authorization')) {
+                this.#authorization = response.getHeader('Authorization');
+            }
+            return response;
+        }
+        catch (error) {
+            if (error?.constructor?.name === 'Unauthorized') {
+                this.#authorization = undefined;
+            }
+            throw error;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { default as AuthenticationMiddleware } from './AuthenticationMiddleware';
+export { default as RequesterMiddleware } from './RequesterMiddleware';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { default as AuthenticationMiddleware } from './AuthenticationMiddleware';
+export { default as RequesterMiddleware } from './RequesterMiddleware';

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@jitar-plugins/authentication",
+  "private": false,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "lint": "eslint",
+    "review": "npm run build && npm run lint",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "types": "dist/index.d.ts",
+  "exports": "./dist/index.js",
+  "peerDependencies": {
+    "@theshelf/authentication": "^0.0.2",
+    "jitar": "^0.10.3"
+  }
+}