@twin.org/api-auth-entity-storage-service 0.0.1-next.10

package/dist/esm/index.mjs

@@ -0,0 +1,609 @@
+import { property, entity, EntitySchemaFactory, EntitySchemaHelper } from '@twin.org/entity';
+import { HttpErrorHelper } from '@twin.org/api-models';
+import { Is, UnauthorizedError, Guards, BaseError, ComponentFactory, Converter, GeneralError } from '@twin.org/core';
+import { VaultConnectorFactory } from '@twin.org/vault-models';
+import { Jwt, JwtAlgorithms, HeaderTypes, HttpStatusCode } from '@twin.org/web';
+import { EntityStorageConnectorFactory } from '@twin.org/entity-storage-models';
+import { Blake2b } from '@twin.org/crypto';
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Class defining the storage for user login credentials.
+ */
+let AuthenticationUser = class AuthenticationUser {
+    /**
+     * The user e-mail address.
+     */
+    email;
+    /**
+     * The encrypted password for the user.
+     */
+    password;
+    /**
+     * The salt for the password.
+     */
+    salt;
+    /**
+     * The user identity.
+     */
+    identity;
+};
+__decorate([
+    property({ type: "string", isPrimary: true }),
+    __metadata("design:type", String)
+], AuthenticationUser.prototype, "email", void 0);
+__decorate([
+    property({ type: "string" }),
+    __metadata("design:type", String)
+], AuthenticationUser.prototype, "password", void 0);
+__decorate([
+    property({ type: "string" }),
+    __metadata("design:type", String)
+], AuthenticationUser.prototype, "salt", void 0);
+__decorate([
+    property({ type: "string" }),
+    __metadata("design:type", String)
+], AuthenticationUser.prototype, "identity", void 0);
+AuthenticationUser = __decorate([
+    entity()
+], AuthenticationUser);
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Helper class for token operations.
+ */
+class TokenHelper {
+    /**
+     * Runtime name for the class.
+     * @internal
+     */
+    static _CLASS_NAME = "TokenHelper";
+    /**
+     * Create a new token.
+     * @param vaultConnector The vault connector.
+     * @param signingKeyName The signing key name.
+     * @param subject The subject for the token.
+     * @param ttlMinutes The time to live for the token in minutes.
+     * @returns The new token and its expiry date.
+     */
+    static async createToken(vaultConnector, signingKeyName, subject, ttlMinutes) {
+        // Verify was a success so we can now generate a new token.
+        const nowSeconds = Math.trunc(Date.now() / 1000);
+        const ttlSeconds = ttlMinutes * 60;
+        const jwt = await Jwt.encodeWithSigner({ alg: JwtAlgorithms.EdDSA }, {
+            sub: subject,
+            exp: nowSeconds + ttlSeconds
+        }, async (alg, key, payload) => vaultConnector.sign(signingKeyName, payload));
+        return {
+            token: jwt,
+            expiry: (nowSeconds + ttlSeconds) * 1000
+        };
+    }
+    /**
+     * Verify the token.
+     * @param vaultConnector The vault connector.
+     * @param signingKeyName The signing key name.
+     * @param token The token to verify.
+     * @returns The verified details.
+     * @throws UnauthorizedError if the token is missing, invalid or expired.
+     */
+    static async verify(vaultConnector, signingKeyName, token) {
+        if (!Is.stringValue(token)) {
+            throw new UnauthorizedError(this._CLASS_NAME, "missing");
+        }
+        const decoded = await Jwt.verifyWithVerifier(token, async (alg, key, payload, signature) => vaultConnector.verify(signingKeyName, payload, signature));
+        // If the signature validation failed or some of the header/payload data
+        // is not properly populated then it is unauthorized.
+        if (!decoded.verified ||
+            !Is.object(decoded.header) ||
+            !Is.object(decoded.payload) ||
+            !Is.stringValue(decoded.payload.sub)) {
+            throw new UnauthorizedError(this._CLASS_NAME, "invalidToken");
+        }
+        else if (!Is.empty(decoded.payload?.exp) &&
+            decoded.payload.exp < Math.trunc(Date.now() / 1000)) {
+            throw new UnauthorizedError(this._CLASS_NAME, "expired");
+        }
+        return {
+            header: decoded.header,
+            payload: decoded.payload
+        };
+    }
+    /**
+     * Extract the auth token from the headers, either from the authorization header or the cookie header.
+     * @param headers The headers to extract the token from.
+     * @param cookieName The name of the cookie to extract the token from.
+     * @returns The token if found.
+     */
+    static extractTokenFromHeaders(headers, cookieName) {
+        const authHeader = headers?.[HeaderTypes.Authorization];
+        const cookiesHeader = headers?.[HeaderTypes.Cookie];
+        if (Is.string(authHeader) && authHeader.startsWith("Bearer ")) {
+            return {
+                token: authHeader.slice(7).trim(),
+                location: "authorization"
+            };
+        }
+        else if (Is.notEmpty(cookiesHeader) && Is.stringValue(cookieName)) {
+            const cookies = Is.arrayValue(cookiesHeader) ? cookiesHeader : [cookiesHeader];
+            for (const cookie of cookies) {
+                if (Is.stringValue(cookie)) {
+                    const accessTokenCookie = cookie
+                        .split(";")
+                        .map(c => c.trim())
+                        .find(c => c.startsWith(cookieName));
+                    if (Is.stringValue(accessTokenCookie)) {
+                        return {
+                            token: accessTokenCookie.slice(cookieName.length + 1).trim(),
+                            location: "cookie"
+                        };
+                    }
+                }
+            }
+        }
+    }
+}
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Handle a JWT token in the authorization header or cookies and validate it to populate request context identity.
+ */
+class AuthHeaderProcessor {
+    /**
+     * The default name for the access token as a cookie.
+     * @internal
+     */
+    static DEFAULT_COOKIE_NAME = "access_token";
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "AuthHeaderProcessor";
+    /**
+     * The vault for the keys.
+     * @internal
+     */
+    _vaultConnector;
+    /**
+     * The name of the key to retrieve from the vault for signing JWT.
+     * @internal
+     */
+    _signingKeyName;
+    /**
+     * The name of the cookie to use for the token.
+     * @internal
+     */
+    _cookieName;
+    /**
+     * The node identity.
+     * @internal
+     */
+    _nodeIdentity;
+    /**
+     * Create a new instance of AuthCookiePreProcessor.
+     * @param options Options for the processor.
+     * @param options.vaultConnectorType The vault for the private keys, defaults to "vault".
+     * @param options.config The configuration for the processor.
+     */
+    constructor(options) {
+        this._vaultConnector = VaultConnectorFactory.get(options?.vaultConnectorType ?? "vault");
+        this._signingKeyName = options?.config?.signingKeyName ?? "auth-signing";
+        this._cookieName = options?.config?.cookieName ?? AuthHeaderProcessor.DEFAULT_COOKIE_NAME;
+    }
+    /**
+     * The service needs to be started when the application is initialized.
+     * @param nodeIdentity The identity of the node.
+     * @param nodeLoggingConnectorType The node logging connector type, defaults to "node-logging".
+     * @returns Nothing.
+     */
+    async start(nodeIdentity, nodeLoggingConnectorType) {
+        Guards.string(this.CLASS_NAME, "nodeIdentity", nodeIdentity);
+        this._nodeIdentity = nodeIdentity;
+    }
+    /**
+     * Pre process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param requestIdentity The identity context for the request.
+     * @param processorState The state handed through the processors.
+     */
+    async pre(request, response, route, requestIdentity, processorState) {
+        if (!Is.empty(route) && !(route.skipAuth ?? false)) {
+            try {
+                const tokenAndLocation = TokenHelper.extractTokenFromHeaders(request.headers, this._cookieName);
+                const headerAndPayload = await TokenHelper.verify(this._vaultConnector, `${this._nodeIdentity}/${this._signingKeyName}`, tokenAndLocation?.token);
+                requestIdentity.userIdentity = headerAndPayload.payload?.sub;
+                processorState.authToken = tokenAndLocation?.token;
+                processorState.authTokenLocation = tokenAndLocation?.location;
+            }
+            catch (err) {
+                const error = BaseError.fromError(err);
+                HttpErrorHelper.buildResponse(response, error, HttpStatusCode.unauthorized);
+            }
+        }
+    }
+    /**
+     * Post process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param requestIdentity The identity context for the request.
+     * @param processorState The state handed through the processors.
+     */
+    async post(request, response, route, requestIdentity, processorState) {
+        const responseAuthOperation = processorState?.authOperation;
+        // We don't populate the cookie if the incoming request was from an authorization header.
+        if (!Is.empty(route) &&
+            Is.stringValue(responseAuthOperation) &&
+            processorState.authTokenLocation !== "authorization") {
+            if ((responseAuthOperation === "login" || responseAuthOperation === "refresh") &&
+                Is.stringValue(response.body?.token)) {
+                response.headers ??= {};
+                response.headers["Set-Cookie"] =
+                    `${this._cookieName}=${response.body.token}; Secure; HttpOnly; SameSite=None; Path=/`;
+                delete response.body.token;
+            }
+            else if (responseAuthOperation === "logout") {
+                response.headers ??= {};
+                response.headers["Set-Cookie"] =
+                    `${this._cookieName}=; Max-Age=0; Secure; HttpOnly; SameSite=None; Path=/`;
+            }
+        }
+    }
+}
+
+/**
+ * The source used when communicating about these routes.
+ */
+const ROUTES_SOURCE = "authenticationRoutes";
+/**
+ * The tag to associate with the routes.
+ */
+const tagsAuthentication = [
+    {
+        name: "Authentication",
+        description: "Authentication endpoints for the REST server."
+    }
+];
+/**
+ * The REST routes for authentication.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+function generateRestRoutesAuthentication(baseRouteName, componentName) {
+    const loginRoute = {
+        operationId: "authenticationLogin",
+        summary: "Login to the server",
+        tag: tagsAuthentication[0].name,
+        method: "POST",
+        path: `${baseRouteName}/login`,
+        handler: async (httpRequestContext, request) => authenticationLogin(httpRequestContext, componentName, request),
+        requestType: {
+            type: "ILoginRequest",
+            examples: [
+                {
+                    id: "loginRequestExample",
+                    description: "The request to login to the server.",
+                    request: {
+                        body: {
+                            email: "user@example.com",
+                            password: "MyPassword123!"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "ILoginResponse",
+                examples: [
+                    {
+                        id: "loginResponseExample",
+                        description: "The response for the login request.",
+                        response: {
+                            body: {
+                                token: "eyJhbGciOiJIU...sw5c",
+                                expiry: 1722514341067
+                            }
+                        }
+                    }
+                ]
+            },
+            {
+                type: "IUnauthorizedResponse"
+            }
+        ],
+        skipAuth: true
+    };
+    const logoutRoute = {
+        operationId: "authenticationLogout",
+        summary: "Logout from the server",
+        tag: tagsAuthentication[0].name,
+        method: "GET",
+        path: `${baseRouteName}/logout`,
+        handler: async (httpRequestContext, request) => authenticationLogout(httpRequestContext, componentName, request),
+        requestType: {
+            type: "ILogoutRequest",
+            examples: [
+                {
+                    id: "logoutRequestExample",
+                    description: "The request to logout from the server.",
+                    request: {
+                        query: {
+                            token: "eyJhbGciOiJIU...sw5c"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "INoContentResponse"
+            }
+        ],
+        skipAuth: true
+    };
+    const refreshTokenRoute = {
+        operationId: "authenticationRefreshToken",
+        summary: "Refresh an authentication token",
+        tag: tagsAuthentication[0].name,
+        method: "GET",
+        path: `${baseRouteName}/refresh`,
+        handler: async (httpRequestContext, request) => authenticationRefreshToken(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IRefreshTokenRequest",
+            examples: [
+                {
+                    id: "refreshTokenRequestExample",
+                    description: "The request to refresh an auth token.",
+                    request: {
+                        query: {
+                            token: "eyJhbGciOiJIU...sw5c"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "IRefreshTokenResponse",
+                examples: [
+                    {
+                        id: "refreshTokenResponseExample",
+                        description: "The response for the refresh token request.",
+                        response: {
+                            body: {
+                                token: "eyJhbGciOiJIU...sw5c",
+                                expiry: 1722514341067
+                            }
+                        }
+                    }
+                ]
+            },
+            {
+                type: "IUnauthorizedResponse"
+            }
+        ]
+    };
+    return [loginRoute, logoutRoute, refreshTokenRoute];
+}
+/**
+ * Login to the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function authenticationLogin(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.body", request.body);
+    const component = ComponentFactory.get(componentName);
+    const result = await component.login(request.body.email, request.body.password);
+    // Need to give a hint to any auth processors about the operation
+    // in case they need to manipulate the response
+    httpRequestContext.processorState.authOperation = "login";
+    return {
+        body: result
+    };
+}
+/**
+ * Logout from the server.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function authenticationLogout(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    const component = ComponentFactory.get(componentName);
+    await component.logout(request.query?.token);
+    // Need to give a hint to any auth processors about the operation
+    // in case they need to manipulate the response
+    httpRequestContext.processorState.authOperation = "logout";
+    return {
+        statusCode: HttpStatusCode.noContent
+    };
+}
+/**
+ * Refresh the login token.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function authenticationRefreshToken(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    const component = ComponentFactory.get(componentName);
+    // If the token is not in the query, then maybe an auth processor has extracted it
+    // and stored it in the processor state
+    const token = request.query?.token ?? httpRequestContext.processorState.authToken;
+    const result = await component.refresh(token);
+    // Need to give a hint to any auth processors about the operation
+    // in case they need to manipulate the response
+    httpRequestContext.processorState.authOperation = "refresh";
+    return {
+        body: result
+    };
+}
+
+const restEntryPoints = [
+    {
+        name: "authentication",
+        defaultBaseRoute: "authentication",
+        tags: tagsAuthentication,
+        generateRoutes: generateRestRoutesAuthentication
+    }
+];
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Initialize the schema for the authentication service.
+ */
+function initSchema() {
+    EntitySchemaFactory.register("AuthenticationUser", () => EntitySchemaHelper.getSchema(AuthenticationUser));
+}
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Helper class for password operations.
+ */
+class PasswordHelper {
+    /**
+     * Runtime name for the class.
+     * @internal
+     */
+    static _CLASS_NAME = "PasswordHelper";
+    /**
+     * Hash the password for the user.
+     * @param passwordBytes The password bytes.
+     * @param saltBytes The salt bytes.
+     * @returns The hashed password.
+     */
+    static async hashPassword(passwordBytes, saltBytes) {
+        Guards.uint8Array(PasswordHelper._CLASS_NAME, "passwordBytes", passwordBytes);
+        Guards.uint8Array(PasswordHelper._CLASS_NAME, "saltBytes", saltBytes);
+        const combined = new Uint8Array(saltBytes.length + passwordBytes.length);
+        combined.set(saltBytes);
+        combined.set(passwordBytes, saltBytes.length);
+        const hashedPassword = Blake2b.sum256(combined);
+        return Converter.bytesToBase64(hashedPassword);
+    }
+}
+
+/**
+ * Implementation of the authentication component using entity storage.
+ */
+class EntityStorageAuthenticationService {
+    /**
+     * Default TTL in minutes.
+     * @internal
+     */
+    static _DEFAULT_TTL_MINUTES = 60;
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "EntityStorageAuthenticationService";
+    /**
+     * The entity storage for users.
+     * @internal
+     */
+    _userEntityStorage;
+    /**
+     * The vault for the keys.
+     * @internal
+     */
+    _vaultConnector;
+    /**
+     * The name of the key to retrieve from the vault for signing JWT.
+     * @internal
+     */
+    _signingKeyName;
+    /**
+     * The default TTL for the token.
+     * @internal
+     */
+    _defaultTtlMinutes;
+    /**
+     * The node identity.
+     * @internal
+     */
+    _nodeIdentity;
+    /**
+     * Create a new instance of EntityStorageAuthentication.
+     * @param options The dependencies for the identity connector.
+     * @param options.userEntityStorageType The entity storage for the users, defaults to "authentication-user".
+     * @param options.vaultConnectorType The vault for the private keys, defaults to "vault".
+     * @param options.config The configuration for the authentication.
+     */
+    constructor(options) {
+        this._userEntityStorage = EntityStorageConnectorFactory.get(options?.userEntityStorageType ?? "authentication-user");
+        this._vaultConnector = VaultConnectorFactory.get(options?.vaultConnectorType ?? "vault");
+        this._signingKeyName = options?.config?.signingKeyName ?? "auth-signing";
+        this._defaultTtlMinutes =
+            options?.config?.defaultTtlMinutes ?? EntityStorageAuthenticationService._DEFAULT_TTL_MINUTES;
+    }
+    /**
+     * The service needs to be started when the application is initialized.
+     * @param nodeIdentity The identity of the node.
+     * @param nodeLoggingConnectorType The node logging connector type, defaults to "node-logging".
+     * @returns Nothing.
+     */
+    async start(nodeIdentity, nodeLoggingConnectorType) {
+        Guards.string(this.CLASS_NAME, "nodeIdentity", nodeIdentity);
+        this._nodeIdentity = nodeIdentity;
+    }
+    /**
+     * Perform a login for the user.
+     * @param email The email address for the user.
+     * @param password The password for the user.
+     * @returns The authentication token for the user, if it uses a mechanism with public access.
+     */
+    async login(email, password) {
+        Guards.stringValue(this.CLASS_NAME, "email", email);
+        Guards.stringValue(this.CLASS_NAME, "password", password);
+        try {
+            const user = await this._userEntityStorage.get(email);
+            if (!user) {
+                throw new GeneralError(this.CLASS_NAME, "userNotFound");
+            }
+            const saltBytes = Converter.base64ToBytes(user.salt);
+            const passwordBytes = Converter.utf8ToBytes(password);
+            const hashedPassword = await PasswordHelper.hashPassword(passwordBytes, saltBytes);
+            if (hashedPassword !== user.password) {
+                throw new GeneralError(this.CLASS_NAME, "passwordMismatch");
+            }
+            const tokenAndExpiry = await TokenHelper.createToken(this._vaultConnector, `${this._nodeIdentity}/${this._signingKeyName}`, user.identity, this._defaultTtlMinutes);
+            return tokenAndExpiry;
+        }
+        catch (error) {
+            throw new UnauthorizedError(this.CLASS_NAME, "loginFailed", error);
+        }
+    }
+    /**
+     * Logout the current user.
+     * @param token The token to logout, if it uses a mechanism with public access.
+     * @returns Nothing.
+     */
+    async logout(token) {
+        // Nothing to do here.
+    }
+    /**
+     * Refresh the token.
+     * @param token The token to refresh, if it uses a mechanism with public access.
+     * @returns The refreshed token, if it uses a mechanism with public access.
+     */
+    async refresh(token) {
+        // If the verify fails on the current token then it will throw an exception.
+        const headerAndPayload = await TokenHelper.verify(this._vaultConnector, `${this._nodeIdentity}/${this._signingKeyName}`, token);
+        const refreshTokenAndExpiry = await TokenHelper.createToken(this._vaultConnector, `${this._nodeIdentity}/${this._signingKeyName}`, headerAndPayload.payload.sub ?? "", this._defaultTtlMinutes);
+        return refreshTokenAndExpiry;
+    }
+}
+
+export { AuthHeaderProcessor, AuthenticationUser, EntityStorageAuthenticationService, PasswordHelper, TokenHelper, authenticationLogin, authenticationLogout, authenticationRefreshToken, generateRestRoutesAuthentication, initSchema, restEntryPoints, tagsAuthentication };

package/dist/types/entities/authenticationUser.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Class defining the storage for user login credentials.
+ */
+export declare class AuthenticationUser {
+    /**
+     * The user e-mail address.
+     */
+    email: string;
+    /**
+     * The encrypted password for the user.
+     */
+    password: string;
+    /**
+     * The salt for the password.
+     */
+    salt: string;
+    /**
+     * The user identity.
+     */
+    identity: string;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./entities/authenticationUser";
+export * from "./models/IAuthHeaderProcessorConfig";
+export * from "./models/IEntityStorageAuthenticationServiceConfig";
+export * from "./processors/authHeaderProcessor";
+export * from "./restEntryPoints";
+export * from "./routes/entityStorageAuthenticationRoutes";
+export * from "./schema";
+export * from "./services/entityStorageAuthenticationService";
+export * from "./utils/passwordHelper";
+export * from "./utils/tokenHelper";

package/dist/types/models/IAuthHeaderProcessorConfig.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Configuration for the authentication header processor
+ */
+export interface IAuthHeaderProcessorConfig {
+    /**
+     * The name of the key to retrieve from the vault for signing JWT.
+     * @default auth-signing
+     */
+    signingKeyName?: string;
+    /**
+     * The name of the cookie to use for the token.
+     * @default access_token
+     */
+    cookieName?: string;
+}

package/dist/types/models/IEntityStorageAuthenticationServiceConfig.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Configuration for the entity storage authentication service.
+ */
+export interface IEntityStorageAuthenticationServiceConfig {
+    /**
+     * The name of the key to retrieve from the vault for signing JWT.
+     * @default auth-signing
+     */
+    signingKeyName?: string;
+    /**
+     * The default time to live for the JWT.
+     * @default 1440
+     */
+    defaultTtlMinutes?: number;
+}