@theshelf/authentication 0.0.1

package/README.md

@@ -0,0 +1,115 @@
+
+# Authentication | The Shelf
+
+The authentication package provides a universal interaction layer with an actual identity provider solution.
+
+This package is based on the following authentication flow:
+
+1. Browser redirects to the IDP login page.
+2. User authenticate at the IDP.
+3. IDP provides identity information to this package.
+4. This package starts a session based on the provided identity.
+5. Sessions can be refreshed via this package.
+6. Until the user logs out via this package.
+
+## Installation
+
+```bash
+npm install @theshelf/authentication
+```
+
+## Implementations
+
+Currently, there is only one implementation:
+
+* **OpenID** - persistent document storage.
+
+## Configuration
+
+The used implementation needs to be configured in the `.env` file, together with the client URL.
+
+```env
+AUTHENTICATION_IMPLEMENTATION="openid"
+AUTHENTICATION_CLIENT_URI="https://application.com/authenticate"
+```
+
+In case of OpenID, additional configuration is required.
+
+```env
+OPENID_ISSUER="https://identityprovider.com"
+OPENID_CLIENT_ID="openid"
+OPENID_CLIENT_SECRET=""
+OPENID_REDIRECT_PATH="https://application.com/login"
+OPENID_ALLOW_INSECURE_REQUESTS=false
+```
+
+## How to use
+
+An instance of the configured identity provider implementation can be imported for performing authentication operations.
+
+```ts
+import identityProvider from '@theshelf/authentication';
+
+// Perform operations with the identityProvider instance
+```
+
+### Operations
+
+```ts
+import identityProvider, { Session } from '@theshelf/authentication';
+
+// Open connection
+await identityProvider.connect();
+
+// Close connection
+await identityProvider.disconnect();
+
+// Request the URL of the login page
+const loginUrl: string = await identityProvider.getLoginUrl();
+
+// Handle a login and get a session
+// Throws `LoginFailed` if not successful
+const firstSession: Session = await identityProvider.login(providedIdentity);
+
+// Refresh a session
+// Throws `LoginFailed` if not successful
+const secondSession: Session = await identityProvider.refresh(firstSession);
+
+// Logout
+await identityProvider.logout(secondSession);
+```
+
+### Session structure
+
+The session has the following structure.
+
+```ts
+type Session = {
+    key?: string;
+    requester?: unknown;
+    identity: Identity;
+    accessToken: Token;
+    refreshToken: Token;
+    expires: Date;
+};
+```
+
+Every session has a unique key that will be provided to external clients. This key is an unrelated hash value that contains no session information. It's ony used for referencing and storage.
+
+The requester represents the actual logged in user retrieved from the identity information (email), and can be stored in the session for quick reference. The full Identity structure looks like this.
+
+```ts
+type Identity = {
+    name: string;
+    nickname: string | undefined;
+    picture: string | undefined;
+    email: string;
+    email_verified: boolean;
+};
+```
+
+The access and refresh tokens can be of any type, but is always represented as string. This depends on the configured implementation. In most cases this will be a JWT.
+
+```ts
+type Token = string;
+```

package/dist/definitions/interfaces.d.ts

@@ -0,0 +1,10 @@
+import type { Session } from './types';
+export interface IdentityProvider {
+    get connected(): boolean;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getLoginUrl(origin: string): Promise<string>;
+    login(origin: string, data: Record<string, unknown>): Promise<Session>;
+    refresh(session: Session): Promise<Session>;
+    logout(session: Session): Promise<void>;
+}

package/dist/definitions/interfaces.js

@@ -0,0 +1 @@
+export {};

package/dist/definitions/types.d.ts

@@ -0,0 +1,17 @@
+type Identity = {
+    name: string;
+    nickname: string | undefined;
+    picture: string | undefined;
+    email: string;
+    email_verified: boolean;
+};
+type Token = string;
+type Session = {
+    key?: string;
+    requester?: unknown;
+    identity: Identity;
+    accessToken: Token;
+    refreshToken: Token;
+    expires: Date;
+};
+export type { Identity, Session };

package/dist/definitions/types.js

@@ -0,0 +1 @@
+export {};

package/dist/errors/AuthenticationError.d.ts

@@ -0,0 +1,2 @@
+export default class AuthenticationError extends Error {
+}

package/dist/errors/AuthenticationError.js

@@ -0,0 +1,2 @@
+export default class AuthenticationError extends Error {
+}

package/dist/errors/LoginFailed.d.ts

@@ -0,0 +1,3 @@
+import AuthenticationError from './AuthenticationError';
+export default class LoginFailed extends AuthenticationError {
+}

package/dist/errors/LoginFailed.js

@@ -0,0 +1,3 @@
+import AuthenticationError from './AuthenticationError';
+export default class LoginFailed extends AuthenticationError {
+}

package/dist/errors/NotConnected.d.ts

@@ -0,0 +1,4 @@
+import AuthenticationError from './AuthenticationError';
+export default class NotConnected extends AuthenticationError {
+    constructor(message?: string);
+}

package/dist/errors/NotConnected.js

@@ -0,0 +1,6 @@
+import AuthenticationError from './AuthenticationError';
+export default class NotConnected extends AuthenticationError {
+    constructor(message) {
+        super(message ?? 'Identity provider not connected');
+    }
+}

package/dist/errors/UnknownImplementation.d.ts

@@ -0,0 +1,4 @@
+import AuthenticationError from './AuthenticationError';
+export default class UnknownImplementation extends AuthenticationError {
+    constructor(name: string);
+}

package/dist/errors/UnknownImplementation.js

@@ -0,0 +1,6 @@
+import AuthenticationError from './AuthenticationError';
+export default class UnknownImplementation extends AuthenticationError {
+    constructor(name) {
+        super(`Unknown authentication implementation: ${name}`);
+    }
+}

package/dist/implementation.d.ts

@@ -0,0 +1,3 @@
+import type { IdentityProvider } from './definitions/interfaces';
+declare const _default: IdentityProvider;
+export default _default;

package/dist/implementation.js

@@ -0,0 +1,12 @@
+import UnknownImplementation from './errors/UnknownImplementation';
+import createOpenID from './implementations/openid/create';
+const implementations = new Map([
+    ['openid', createOpenID],
+]);
+const DEFAULT_AUTHENTICATION_IMPLEMENTATION = 'openid';
+const implementationName = process.env.AUTHENTICATION_IMPLEMENTATION ?? DEFAULT_AUTHENTICATION_IMPLEMENTATION;
+const creator = implementations.get(implementationName.toLowerCase());
+if (creator === undefined) {
+    throw new UnknownImplementation(implementationName);
+}
+export default creator();

package/dist/implementations/openid/OpenID.d.ts

@@ -0,0 +1,21 @@
+import type { IdentityProvider } from '../../definitions/interfaces';
+import type { Session } from '../../definitions/types';
+type OpenIDConfiguration = {
+    issuer: string;
+    clientId: string;
+    clientSecret: string;
+    redirectPath: string;
+    allowInsecureRequests: boolean;
+};
+export default class OpenID implements IdentityProvider {
+    #private;
+    constructor(configuration: OpenIDConfiguration);
+    get connected(): boolean;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getLoginUrl(origin: string): Promise<string>;
+    login(origin: string, data: Record<string, unknown>): Promise<Session>;
+    refresh(session: Session): Promise<Session>;
+    logout(session: Session): Promise<void>;
+}
+export {};

package/dist/implementations/openid/OpenID.js

@@ -0,0 +1,105 @@
+import { allowInsecureRequests, authorizationCodeGrant, buildAuthorizationUrlWithPAR, calculatePKCECodeChallenge, discovery, fetchUserInfo, randomPKCECodeVerifier, refreshTokenGrant, tokenRevocation } from 'openid-client';
+import LoginFailed from '../../errors/LoginFailed';
+import NotConnected from '../../errors/NotConnected';
+export default class OpenID {
+    #providerConfiguration;
+    #clientConfiguration;
+    #codeVerifier = randomPKCECodeVerifier();
+    constructor(configuration) {
+        this.#providerConfiguration = configuration;
+    }
+    get connected() {
+        return this.#clientConfiguration !== undefined;
+    }
+    async connect() {
+        const issuer = new URL(this.#providerConfiguration.issuer);
+        const clientId = this.#providerConfiguration.clientId;
+        const clientSecret = this.#providerConfiguration.clientSecret;
+        const requestOptions = this.#getRequestOptions();
+        this.#clientConfiguration = await discovery(issuer, clientId, clientSecret, undefined, requestOptions);
+    }
+    async disconnect() {
+        this.#clientConfiguration = undefined;
+    }
+    async getLoginUrl(origin) {
+        const redirect_uri = new URL(this.#providerConfiguration.redirectPath, origin).href;
+        const scope = 'openid profile email';
+        const code_challenge = await calculatePKCECodeChallenge(this.#codeVerifier);
+        const code_challenge_method = 'S256';
+        const parameters = {
+            redirect_uri,
+            scope,
+            code_challenge,
+            code_challenge_method
+        };
+        const clientConfiguration = this.#getClientConfiguration();
+        const redirectTo = await buildAuthorizationUrlWithPAR(clientConfiguration, parameters);
+        return redirectTo.href;
+    }
+    async login(origin, data) {
+        const clientConfiguration = this.#getClientConfiguration();
+        const url = new URL(this.#providerConfiguration.redirectPath, origin);
+        url.searchParams.set('session_state', data.session_state);
+        url.searchParams.set('iss', data.iss);
+        url.searchParams.set('code', data.code);
+        const tokens = await authorizationCodeGrant(clientConfiguration, url, {
+            pkceCodeVerifier: this.#codeVerifier,
+            idTokenExpected: true
+        });
+        const access_token = tokens.access_token;
+        const claims = this.#getClaims(tokens);
+        const sub = claims.sub;
+        const expires = claims.exp * 1000;
+        const userInfo = await fetchUserInfo(clientConfiguration, access_token, sub);
+        const identity = {
+            name: userInfo.name,
+            nickname: userInfo.nickname,
+            picture: userInfo.picture,
+            email: userInfo.email,
+            email_verified: userInfo.email_verified
+        };
+        return {
+            identity: identity,
+            accessToken: tokens.access_token,
+            refreshToken: tokens.refresh_token,
+            expires: new Date(expires)
+        };
+    }
+    async refresh(session) {
+        const config = this.#getClientConfiguration();
+        const tokens = await refreshTokenGrant(config, session.refreshToken);
+        const claims = this.#getClaims(tokens);
+        const expires = claims.exp * 1000;
+        return {
+            requester: session.requester,
+            identity: session.identity,
+            accessToken: tokens.access_token,
+            refreshToken: tokens.refresh_token,
+            expires: new Date(expires)
+        };
+    }
+    logout(session) {
+        const config = this.#getClientConfiguration();
+        return tokenRevocation(config, session.refreshToken);
+    }
+    #getClientConfiguration() {
+        if (this.#clientConfiguration === undefined) {
+            throw new NotConnected('OpenID client not connected');
+        }
+        return this.#clientConfiguration;
+    }
+    #getRequestOptions() {
+        const options = {};
+        if (this.#providerConfiguration.allowInsecureRequests) {
+            options.execute = [allowInsecureRequests];
+        }
+        return options;
+    }
+    #getClaims(tokens) {
+        const claims = tokens.claims();
+        if (claims === undefined) {
+            throw new LoginFailed('No claims in ID token');
+        }
+        return claims;
+    }
+}

package/dist/implementations/openid/create.d.ts

@@ -0,0 +1,2 @@
+import OpenID from './OpenID';
+export default function create(): OpenID;

package/dist/implementations/openid/create.js

@@ -0,0 +1,9 @@
+import OpenID from './OpenID';
+export default function create() {
+    const issuer = process.env.OPENID_ISSUER ?? 'undefined';
+    const clientId = process.env.OPENID_CLIENT_ID ?? 'undefined';
+    const clientSecret = process.env.OPENID_CLIENT_SECRET ?? 'undefined';
+    const redirectPath = process.env.OPENID_REDIRECT_PATH ?? 'undefined';
+    const allowInsecureRequests = process.env.OPENID_ALLOW_INSECURE_REQUESTS === 'true';
+    return new OpenID({ issuer, clientId, clientSecret, redirectPath, allowInsecureRequests });
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './definitions/interfaces';
+export * from './definitions/types';
+export { default as AuthenticationError } from './errors/AuthenticationError';
+export { default as NotConnected } from './errors/NotConnected';
+export { default as UnknownImplementation } from './errors/UnknownImplementation';
+export { default } from './implementation';

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from './definitions/interfaces';
+export * from './definitions/types';
+export { default as AuthenticationError } from './errors/AuthenticationError';
+export { default as NotConnected } from './errors/NotConnected';
+export { default as UnknownImplementation } from './errors/UnknownImplementation';
+export { default } from './implementation';

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@theshelf/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 clean && npm run build"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "types": "dist/index.d.ts",
+  "exports": "./dist/index.js",
+  "dependencies": {
+    "openid-client": "6.8.1"
+  }
+}