@appweaver/data 0.0.0-stage → 2.0.0

package/resource/utils/text-search-util.d.ts

@@ -0,0 +1,14 @@
+/** The placeholder a text search object marks the searched text with. */
+export declare const TEXT_SEARCH_PLACEHOLDER = "{input}";
+/**
+ * Builds the database filter of a text search object for the searched text,
+ * replacing every placeholder occurrence in its string values (i.e.
+ * `'{input}'`) with the text. An `OR` given as an object is turned into the
+ * list the database expects, each entry becoming one condition, the way the
+ * `_or` operator of a query filter reads it.
+ *
+ * @param {Object} template The text search object configured on the service.
+ * @param {string} input The searched text.
+ * @return {Object} A new filter object, the template is left untouched.
+ */
+export declare function bindTextSearch(template: any, input: string): any;

package/resource/utils/text-search-util.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEXT_SEARCH_PLACEHOLDER = void 0;
+exports.bindTextSearch = bindTextSearch;
+const common_1 = require("@appweaver/common");
+/** The placeholder a text search object marks the searched text with. */
+exports.TEXT_SEARCH_PLACEHOLDER = '{input}';
+/**
+ * Builds the database filter of a text search object for the searched text,
+ * replacing every placeholder occurrence in its string values (i.e.
+ * `'{input}'`) with the text. An `OR` given as an object is turned into the
+ * list the database expects, each entry becoming one condition, the way the
+ * `_or` operator of a query filter reads it.
+ *
+ * @param {Object} template The text search object configured on the service.
+ * @param {string} input The searched text.
+ * @return {Object} A new filter object, the template is left untouched.
+ */
+function bindTextSearch(template, input) {
+    if ((0, common_1.isString)(template)) {
+        return template.replaceAll(exports.TEXT_SEARCH_PLACEHOLDER, input);
+    }
+    if ((0, common_1.isArray)(template)) {
+        return template.map((item) => bindTextSearch(item, input));
+    }
+    if (!(0, common_1.isPlainObject)(template)) {
+        return template;
+    }
+    const bound = {};
+    for (const [key, value] of Object.entries(template)) {
+        bound[key] =
+            key === 'OR' && (0, common_1.isPlainObject)(value)
+                ? Object.entries(value).map(([field, condition]) => ({
+                    [field]: bindTextSearch(condition, input)
+                }))
+                : bindTextSearch(value, input);
+    }
+    return bound;
+}

package/resources.d.ts

@@ -0,0 +1,10 @@
+export { default as apiKey } from './security/resources/api-key/model';
+export { default as connectedAccount } from './security/resources/connected-account/model';
+export { default as oneTimeToken } from './security/resources/one-time-token/model';
+export { default as role } from './security/resources/role/model';
+export { default as permission } from './security/resources/permission/model';
+export { default as seeder } from './seeder/resources/seeder/model';
+export { default as file } from './storage/resources/file/model';
+export { default as apiKeyService } from './security/resources/api-key/service';
+export { default as connectedAccountService } from './security/resources/connected-account/service';
+export { default as apiKeyPolicy } from './security/resources/api-key/policy';

package/resources.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiKeyPolicy = exports.connectedAccountService = exports.apiKeyService = exports.file = exports.seeder = exports.permission = exports.role = exports.oneTimeToken = exports.connectedAccount = exports.apiKey = void 0;
+var model_1 = require("./security/resources/api-key/model");
+Object.defineProperty(exports, "apiKey", { enumerable: true, get: function () { return __importDefault(model_1).default; } });
+var model_2 = require("./security/resources/connected-account/model");
+Object.defineProperty(exports, "connectedAccount", { enumerable: true, get: function () { return __importDefault(model_2).default; } });
+var model_3 = require("./security/resources/one-time-token/model");
+Object.defineProperty(exports, "oneTimeToken", { enumerable: true, get: function () { return __importDefault(model_3).default; } });
+var model_4 = require("./security/resources/role/model");
+Object.defineProperty(exports, "role", { enumerable: true, get: function () { return __importDefault(model_4).default; } });
+var model_5 = require("./security/resources/permission/model");
+Object.defineProperty(exports, "permission", { enumerable: true, get: function () { return __importDefault(model_5).default; } });
+var model_6 = require("./seeder/resources/seeder/model");
+Object.defineProperty(exports, "seeder", { enumerable: true, get: function () { return __importDefault(model_6).default; } });
+var model_7 = require("./storage/resources/file/model");
+Object.defineProperty(exports, "file", { enumerable: true, get: function () { return __importDefault(model_7).default; } });
+var service_1 = require("./security/resources/api-key/service");
+Object.defineProperty(exports, "apiKeyService", { enumerable: true, get: function () { return __importDefault(service_1).default; } });
+var service_2 = require("./security/resources/connected-account/service");
+Object.defineProperty(exports, "connectedAccountService", { enumerable: true, get: function () { return __importDefault(service_2).default; } });
+var policy_1 = require("./security/resources/api-key/policy");
+Object.defineProperty(exports, "apiKeyPolicy", { enumerable: true, get: function () { return __importDefault(policy_1).default; } });

package/security/auth-config.d.ts

@@ -0,0 +1,23 @@
+export declare const passwordConfig: Readonly<{
+    ENABLED: boolean;
+    MIN_LENGTH: number;
+    MAX_LENGTH: number;
+    UPPERCASE: boolean;
+    LOWERCASE: boolean;
+    NUMERIC: boolean;
+    SPECIAL: boolean;
+}>;
+export declare const apiKeyConfig: Readonly<{
+    MAX_DURATION?: number | undefined;
+    ENABLED: boolean;
+    KEEP_DATABASE_TABLE: boolean;
+    HEADER_NAME: string;
+    DELIMITER: string;
+}>;
+export declare const systemConfig: Readonly<{
+    ADMIN_INITIAL_PASSWORD?: string | undefined;
+    ADMIN_INITIAL_EMAIL: string;
+}>;
+export declare const connectedAccountConfig: Readonly<{
+    CONNECTED_ACCOUNTS_KEEP_DATABASE_TABLE: boolean;
+}>;

package/security/auth-config.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connectedAccountConfig = exports.systemConfig = exports.apiKeyConfig = exports.passwordConfig = void 0;
+const typebox_1 = require("@sinclair/typebox");
+const common_1 = require("@appweaver/common");
+exports.passwordConfig = (0, common_1.defineConfig)('security.password', {
+    /** Enable password-based authentication. Default: `true`. */
+    ENABLED: typebox_1.Type.Boolean({ default: true }),
+    /** Minimum password length. Default: `8`. */
+    MIN_LENGTH: typebox_1.Type.Integer({ default: 8 }),
+    /** Maximum password length. Default: `100`. */
+    MAX_LENGTH: typebox_1.Type.Integer({ default: 100 }),
+    /** Require at least one uppercase letter. Default: `true`. */
+    UPPERCASE: typebox_1.Type.Boolean({ default: true }),
+    /** Require at least one lowercase letter. Default: `true`. */
+    LOWERCASE: typebox_1.Type.Boolean({ default: true }),
+    /** Require at least one digit. Default: `true`. */
+    NUMERIC: typebox_1.Type.Boolean({ default: true }),
+    /** Require at least one special character. Default: `true`. */
+    SPECIAL: typebox_1.Type.Boolean({ default: true })
+});
+exports.apiKeyConfig = (0, common_1.defineConfig)('security.apiKey', {
+    /** Enable API key authentication. Default: `false`. */
+    ENABLED: typebox_1.Type.Boolean({ default: false }),
+    /** Keep the API key database table after migrations. Default: `false`. */
+    KEEP_DATABASE_TABLE: typebox_1.Type.Boolean({ default: false }),
+    /** Request the header name for the API key. Default: `'x-api-key'`. */
+    HEADER_NAME: typebox_1.Type.String({ default: 'x-api-key' }),
+    /** Maximum API key validity duration in milliseconds. */
+    MAX_DURATION: typebox_1.Type.Optional(typebox_1.Type.Integer()),
+    /** Prefix delimiter between key ID and secret value. Default: `'AK'`. */
+    DELIMITER: typebox_1.Type.String({ default: 'AK' })
+});
+exports.systemConfig = (0, common_1.defineConfig)('system', {
+    /** Initial admin account email created on the first run. Default: `'admin@appweaver.co'`. */
+    ADMIN_INITIAL_EMAIL: typebox_1.Type.String({ default: 'admin@appweaver.co' }),
+    /** Initial admin account password. */
+    ADMIN_INITIAL_PASSWORD: typebox_1.Type.Optional(typebox_1.Type.String())
+});
+exports.connectedAccountConfig = (0, common_1.defineConfig)('security.oauth2', {
+    /** Keep the `ConnectedAccount` database table even when every OAuth2 provider is disabled. Default: `false`. */
+    CONNECTED_ACCOUNTS_KEEP_DATABASE_TABLE: typebox_1.Type.Boolean({ default: false })
+});

package/security/create-auth-resources.d.ts

@@ -0,0 +1,28 @@
+import { Ctor, IResourceService, ModelName, RegistryType, ResourceModel, ResourceModelConfig, ResourceServiceConfig } from '@appweaver/common';
+import { CheckOAuth2UserFn, RegistrationDataFn, RegistrationFilesFn } from '../types/auth';
+/** The fields an auth model adds to the configured ones. */
+type AuthFieldName = 'email' | 'passwordHash' | 'verifiedEmail' | 'twoFactorAuth' | 'enabled' | 'logoutAt' | 'password' | 'roles' | 'apiKeys';
+/**
+ * Creates the resource model of an authenticatable user, adding the email, password, verification, two-factor, and
+ * role fields to the configured ones.
+ *
+ * @param {ResourceModelConfig} modelConfig - The model configuration.
+ * @return {ResourceModel} The created auth resource model.
+ */
+export declare function createAuthModel<S extends string, R extends string, F extends string, V extends string>(modelConfig: ResourceModelConfig<S, R, F, V, AuthFieldName>): ResourceModel;
+/**
+ * Creates the resource service of an authenticatable user, hashing the password on create and update, along with the
+ * callbacks preparing the data and files of a registered user. Once the types are generated, the model, create, and
+ * update types are inferred from the model name.
+ *
+ * @param {ResourceServiceConfig} config - The service configuration with the model name, hooks, and registration
+ * callbacks.
+ * @return {Ctor<IResourceService>} The created service class, defined in the application context.
+ */
+export declare function createAuthService<N extends ModelName, T = RegistryType<N, 'model'>, C = RegistryType<N, 'create'>, U = RegistryType<N, 'update'>>(config: ResourceServiceConfig<T, C, U> & {
+    modelName: N;
+    registrationData?: RegistrationDataFn<C>;
+    registrationFiles?: RegistrationFilesFn;
+    checkOAuth2User?: CheckOAuth2UserFn;
+}): Ctor<IResourceService<T, T, C, U>>;
+export {};

package/security/create-auth-resources.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAuthModel = createAuthModel;
+exports.createAuthService = createAuthService;
+const common_1 = require("@appweaver/common");
+const auth_config_1 = require("./auth-config");
+const helper_1 = require("./helper");
+const create_model_1 = require("../factory/create-model");
+const create_service_1 = require("../factory/create-service");
+/**
+ * Creates the resource model of an authenticatable user, adding the email, password, verification, two-factor, and
+ * role fields to the configured ones.
+ *
+ * @param {ResourceModelConfig} modelConfig - The model configuration.
+ * @return {ResourceModel} The created auth resource model.
+ */
+function createAuthModel(modelConfig) {
+    const config = modelConfig;
+    const authModelScalars = {
+        email: {
+            type: 'string',
+            unique: true,
+            maxLength: 255,
+            format: 'email'
+        },
+        passwordHash: {
+            type: 'string',
+            required: false,
+            hidden: true
+        },
+        verifiedEmail: {
+            type: 'boolean',
+            default: false
+        },
+        twoFactorAuth: {
+            type: 'enum',
+            values: Object.values(common_1.TwoFactorAuth),
+            default: common_1.TwoFactorAuth.None
+        },
+        enabled: {
+            type: 'boolean',
+            default: true
+        },
+        logoutAt: {
+            type: 'dateTime',
+            required: false
+        }
+    };
+    // Override email properties if already present in the model config
+    if (config.scalars?.email?.type === 'string') {
+        authModelScalars.email = {
+            ...authModelScalars.email,
+            ...config.scalars.email
+        };
+    }
+    const authModelVirtual = {
+        password: {
+            type: 'string',
+            required: true,
+            input: {
+                type: 'all'
+            },
+            output: {
+                type: 'none'
+            }
+        }
+    };
+    const authModelRelations = {
+        roles: {
+            model: 'Role',
+            type: 'manyToMany',
+            input: {
+                type: 'all'
+            },
+            output: {
+                type: 'always',
+                include: {
+                    permissions: {
+                        type: 'always'
+                    }
+                }
+            }
+        },
+        ...(auth_config_1.apiKeyConfig.ENABLED
+            ? {
+                apiKeys: {
+                    model: 'ApiKey',
+                    type: 'oneToMany',
+                    mappedBy: (0, common_1.uncapitalize)(config.name),
+                    input: {
+                        type: 'none'
+                    },
+                    output: {
+                        type: 'none'
+                    }
+                }
+            }
+            : {}),
+        ...((0, helper_1.isOAuth2Enabled)()
+            ? {
+                connectedAccounts: {
+                    model: 'ConnectedAccount',
+                    type: 'oneToMany',
+                    mappedBy: (0, common_1.uncapitalize)(config.name),
+                    input: {
+                        type: 'none'
+                    },
+                    output: {
+                        type: 'none'
+                    }
+                }
+            }
+            : {})
+    };
+    const authModelInputOmit = ['verifiedEmail', 'logoutAt'];
+    config.scalars = { ...config.scalars, ...authModelScalars };
+    config.virtual = { ...config.virtual, ...authModelVirtual };
+    config.relations = { ...config.relations, ...authModelRelations };
+    config.create = {
+        ...(config.create ?? {}),
+        omit: [...(config.create?.omit ?? []), ...authModelInputOmit]
+    };
+    config.update = {
+        ...(config.update ?? {}),
+        omit: [...(config.update?.omit ?? []), ...authModelInputOmit]
+    };
+    const model = (0, create_model_1.createModel)(config);
+    model[common_1.RESOURCE_AUTH] = true;
+    return model;
+}
+/**
+ * Creates the resource service of an authenticatable user, hashing the password on create and update, along with the
+ * callbacks preparing the data and files of a registered user. Once the types are generated, the model, create, and
+ * update types are inferred from the model name.
+ *
+ * @param {ResourceServiceConfig} config - The service configuration with the model name, hooks, and registration
+ * callbacks.
+ * @return {Ctor<IResourceService>} The created service class, defined in the application context.
+ */
+function createAuthService(config) {
+    // Capture original functions to invoke after new auth logic
+    const beforeCreate = config.beforeCreate;
+    const beforeUpdate = config.beforeUpdate;
+    config.beforeCreate = async (data) => {
+        await (0, helper_1.updatePasswordHash)(data, data['password']);
+        await beforeCreate?.(data);
+    };
+    config.beforeUpdate = async (id, data) => {
+        await (0, helper_1.updatePasswordHash)(data, data['password'], true);
+        await beforeUpdate?.(id, data);
+    };
+    if (!config.registrationData) {
+        config.registrationData = (_, email, password) => {
+            return {
+                email,
+                password
+            };
+        };
+    }
+    const service = (0, create_service_1.createService)(config);
+    service[common_1.RESOURCE_AUTH] = true;
+    return service;
+}

package/security/helper.d.ts

@@ -0,0 +1,109 @@
+import { AuthUser, IResourceService, ResourceModel, ValidationResult } from '@appweaver/common';
+/**
+ * Evaluates and retrieves the resource authentication model from the available resource models.
+ *
+ * The function iterates through the resource models in the given context and returns the first model
+ * that satisfies the `isResourceAuthModel` condition. If no such model is found, it returns undefined.
+ *
+ * @return {ResourceModel | undefined} The resource authentication model if present, otherwise undefined.
+ */
+export declare function resourceAuthModel(): ResourceModel | undefined;
+/**
+ * Provides authentication service for a resource by identifying and injecting
+ * the appropriate resource authentication service if available.
+ *
+ * @return {IResourceService<AuthUser, AuthUser> | undefined} The resource authentication service
+ *         instance if found, otherwise undefined.
+ */
+export declare function resourceAuthService(): IResourceService<AuthUser, AuthUser> | undefined;
+/**
+ * Hashes a plain text password with the Argon2id function of the runtime and a random salt. The hash holds the
+ * Argon2 parameters and the salt, in the PHC string format `$argon2id$v=19$m=19456,t=2,p=1$<salt>$<key>`.
+ *
+ * @param {string} password - The plain text password to be hashed.
+ * @return {Promise<string>} A promise that resolves to the hashed password.
+ */
+export declare function hashPassword(password: string): Promise<string>;
+/**
+ * Validates a plain text password against a hashed password, using the parameters stored in the hash. A hash not in
+ * the form {@link hashPassword} produces never matches.
+ *
+ * @param {string} password - The plain text password to validate.
+ * @param {string} passwordHash - The hashed password to compare against.
+ * @return {Promise<boolean>} Returns a promise that resolves to `true` if the password matches the hash,
+ * otherwise `false`.
+ */
+export declare function checkPassword(password: string, passwordHash: string): Promise<boolean>;
+/**
+ * Tells whether a password hash was made with other parameters than {@link hashPassword} uses now, so it should be
+ * replaced with a new hash of the password, e.g. on the next successful login.
+ *
+ * @param {string} passwordHash - The stored password hash.
+ * @return {boolean} `true` if the hash is not a current Argon2id hash, otherwise `false`.
+ */
+export declare function needsRehash(passwordHash: string): boolean;
+/**
+ * Updates the password hash for a given user and optionally logs the user out by setting a logout timestamp.
+ *
+ * @param {Partial<AuthUser>} authUser - The user object containing authentication details. Only partial fields are
+ * expected.
+ * @param {string} [password] - The new password to hash and set for the user. If not provided, no password update
+ * occurs.
+ * @param {boolean} [logout=false] - Indicates whether to log the user out by setting the logout timestamp.
+ * @return Resolves when the password hash is updated and optional logout processing is complete.
+ * @throws {AuthError} `AUTH_PASSWORD_WEAK` if the provided password does not satisfy password complexity requirements.
+ */
+export declare function updatePasswordHash(authUser: Partial<AuthUser>, password?: string, logout?: boolean): Promise<void>;
+/**
+ * Validates the complexity of a given password based on the configured rules.
+ * @param {string} password - The password to be validated.
+ * @return {ValidationResult} An object with the validation result and message.
+ */
+export declare function validatePasswordComplexity(password: string): ValidationResult;
+/**
+ * Checks whether at least one OAuth2 provider is enabled, by resolving each OAuth2 auth source to its
+ * `SECURITY_OAUTH2_<PROVIDER>_ENABLED` config flag. New providers are picked up automatically as long as they follow
+ * that naming convention.
+ *
+ * @return {boolean} True when any OAuth2 provider is enabled.
+ */
+export declare function isOAuth2Enabled(): boolean;
+/**
+ * Checks if the given user has a specific role.
+ *
+ * @param {AuthUser} authUser - The authenticated user object containing role information.
+ * @param {string} role - The name of the role to check for.
+ * @return {boolean} True if the user has the specified role; otherwise, false.
+ */
+export declare function hasRole(authUser: AuthUser, role: string): boolean;
+/**
+ * Checks if the authenticated user has the required roles based on the specified operator.
+ *
+ * @param {AuthUser} authUser - The authenticated user whose roles are being checked.
+ * @param {Array<string> | undefined} roles - The list of roles to check against. If undefined, the method returns
+ * true`.
+ * @param {'or' | 'and'} [operator='or'] - The logical operator for role matching. Use 'or' to check if the user has at
+ * least one role, and 'and' to check if the user has all roles.
+ * @return {boolean} Returns `true` if the user satisfies the role check based on the specified operator, otherwise
+ * `false`.
+ */
+export declare function hasRoles(authUser: AuthUser, roles: Array<string> | undefined, operator?: 'or' | 'and'): boolean;
+/**
+ * Determines if the authenticated user has the specified permission.
+ *
+ * @param {AuthUser} authUser - The authenticated user object containing roles and permissions.
+ * @param {string} permission - The name of the permission to check for.
+ * @return {boolean} Returns true if the user has the specified permission, otherwise false.
+ */
+export declare function hasPermission(authUser: AuthUser, permission: string): boolean;
+/**
+ * Checks if the authenticated user has the specified permissions based on the given operator.
+ *
+ * @param {AuthUser} authUser - The authenticated user object.
+ * @param {string[] | undefined} permissions - The list of permissions to check. If undefined, it defaults to granting
+ * access.
+ * @param {'or' | 'and'} [operator='or'] - Determines whether all permissions (and) or at least one permission (or) must
+ * be satisfied.
+ * @return {boolean} Returns true if the user satisfies the permission requirements, false otherwise.
+ */
+export declare function hasPermissions(authUser: AuthUser, permissions: string[] | undefined, operator?: 'or' | 'and'): boolean;