@techelusive/nest-auth 0.0.0-stage → 0.2.0

package/dist/features/settings/settings.defaults.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SETTINGS = void 0;
+/** The default settings live in constants.ts with every other fixed value. */
+var constants_1 = require("../../constants.js");
+Object.defineProperty(exports, "DEFAULT_SETTINGS", { enumerable: true, get: function () { return constants_1.DEFAULT_SETTINGS; } });
+//# sourceMappingURL=settings.defaults.js.map

package/dist/features/settings/settings.defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.defaults.js","sourceRoot":"","sources":["../../../src/features/settings/settings.defaults.ts"],"names":[],"mappings":";;;AAAA,8EAA8E;AAC9E,yCAA+C;AAAtC,6GAAA,gBAAgB,OAAA"}

package/dist/features/settings/settings.service.d.ts

@@ -0,0 +1,44 @@
+import { AuthOptions } from '../../auth-options.js';
+import { AuthSettings, SettingsChanges } from './settings.types';
+/**
+ * Works out the settings in force:
+ *   built-in defaults  ->  settings from your code  ->  changes an admin saved in the database
+ *
+ * Settings from code are checked when the app starts; a mistake stops the app with a clear message.
+ */
+export declare class SettingsService {
+    private readonly database;
+    private readonly settingsFromCode;
+    private cachedSettings?;
+    constructor(options: AuthOptions);
+    /**
+     * The settings in force right now: code settings with admin changes on top.
+     * Cached for a few seconds, so admin changes reach every server quickly without a query per request.
+     *
+     * @returns The full settings.
+     */
+    getSettings(): Promise<AuthSettings>;
+    /**
+     * Saves an admin's changes. Settings not mentioned keep their current values.
+     *
+     * @param changes - Only the sections and fields to change.
+     * @param changedBy - Who made the change, e.g. "admin:<id>".
+     * @returns The settings now in force.
+     * @throws AuthError INVALID_SETTINGS (with `problems`) when a value is not allowed or the
+     *   result would conflict (e.g. no sign-in method left on).
+     */
+    saveAdminChanges(changes: SettingsChanges, changedBy: string): Promise<AuthSettings>;
+    /**
+     * Forgets every admin change; the settings from your code apply again.
+     *
+     * @returns The settings from code.
+     */
+    discardAdminChanges(): Promise<AuthSettings>;
+    /**
+     * Reads the admin's saved changes. If a code update made them invalid, they are ignored
+     * (rather than breaking sign-in for everyone).
+     *
+     * @returns The saved changes, or {} when there are none or they are no longer valid.
+     */
+    private loadAdminChanges;
+}

package/dist/features/settings/settings.service.js

@@ -0,0 +1,112 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SettingsService = void 0;
+const common_1 = require("@nestjs/common");
+const auth_error_1 = require("../../common/auth-error.js");
+const constants_1 = require("../../constants.js");
+const entities_1 = require("../../database/entities/index.js");
+const settings_defaults_1 = require("./settings.defaults");
+const settings_validation_1 = require("./settings.validation");
+/**
+ * Works out the settings in force:
+ *   built-in defaults  ->  settings from your code  ->  changes an admin saved in the database
+ *
+ * Settings from code are checked when the app starts; a mistake stops the app with a clear message.
+ */
+let SettingsService = class SettingsService {
+    database;
+    settingsFromCode;
+    cachedSettings;
+    constructor(options) {
+        this.database = options.dataSource;
+        const problemsInCode = (0, settings_validation_1.findProblemsInChanges)(options.settings ?? {});
+        this.settingsFromCode = (0, settings_validation_1.applySettingsChanges)(settings_defaults_1.DEFAULT_SETTINGS, options.settings);
+        problemsInCode.push(...(0, settings_validation_1.findSettingsConflicts)(this.settingsFromCode));
+        if (problemsInCode.length > 0) {
+            throw new Error(`AuthModule settings are invalid:\n  - ${problemsInCode.join('\n  - ')}`);
+        }
+    }
+    /**
+     * The settings in force right now: code settings with admin changes on top.
+     * Cached for a few seconds, so admin changes reach every server quickly without a query per request.
+     *
+     * @returns The full settings.
+     */
+    getSettings() {
+        const cacheIsFresh = this.cachedSettings && Date.now() - this.cachedSettings.loadedAt < constants_1.SETTINGS_CACHE_SECONDS * constants_1.SECOND_IN_MILLISECONDS;
+        if (!cacheIsFresh) {
+            const settings = this.loadAdminChanges().then((adminChanges) => (0, settings_validation_1.applySettingsChanges)(this.settingsFromCode, adminChanges));
+            settings.catch(() => (this.cachedSettings = undefined));
+            this.cachedSettings = { settings, loadedAt: Date.now() };
+        }
+        return this.cachedSettings.settings;
+    }
+    /**
+     * Saves an admin's changes. Settings not mentioned keep their current values.
+     *
+     * @param changes - Only the sections and fields to change.
+     * @param changedBy - Who made the change, e.g. "admin:<id>".
+     * @returns The settings now in force.
+     * @throws AuthError INVALID_SETTINGS (with `problems`) when a value is not allowed or the
+     *   result would conflict (e.g. no sign-in method left on).
+     */
+    async saveAdminChanges(changes, changedBy) {
+        const problemsInChanges = (0, settings_validation_1.findProblemsInChanges)(changes);
+        if (problemsInChanges.length > 0)
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.invalidSettings, { problems: problemsInChanges });
+        const allAdminChanges = (0, settings_validation_1.combineSettingsChanges)(await this.loadAdminChanges(), changes);
+        const newSettings = (0, settings_validation_1.applySettingsChanges)(this.settingsFromCode, allAdminChanges);
+        const combinedProblems = (0, settings_validation_1.findSettingsConflicts)(newSettings);
+        if (combinedProblems.length > 0)
+            throw new auth_error_1.AuthError(constants_1.AUTH_ERRORS.invalidSettings, { problems: combinedProblems });
+        await this.database.getRepository(entities_1.SettingsEntity).save({ id: constants_1.SETTINGS_ROW_ID, changedValues: allAdminChanges, changedBy });
+        this.cachedSettings = undefined;
+        return newSettings;
+    }
+    /**
+     * Forgets every admin change; the settings from your code apply again.
+     *
+     * @returns The settings from code.
+     */
+    async discardAdminChanges() {
+        await this.database.getRepository(entities_1.SettingsEntity).delete({ id: constants_1.SETTINGS_ROW_ID });
+        this.cachedSettings = undefined;
+        return this.settingsFromCode;
+    }
+    /**
+     * Reads the admin's saved changes. If a code update made them invalid, they are ignored
+     * (rather than breaking sign-in for everyone).
+     *
+     * @returns The saved changes, or {} when there are none or they are no longer valid.
+     */
+    async loadAdminChanges() {
+        const row = await this.database.getRepository(entities_1.SettingsEntity).findOne({ where: { id: constants_1.SETTINGS_ROW_ID } });
+        if (!row)
+            return {};
+        // A code update may have made an old admin change invalid. Fall back to the code settings
+        // rather than break sign-in for everyone.
+        const savedChanges = row.changedValues;
+        const stillValid = (0, settings_validation_1.findProblemsInChanges)(savedChanges).length === 0 &&
+            (0, settings_validation_1.findSettingsConflicts)((0, settings_validation_1.applySettingsChanges)(this.settingsFromCode, savedChanges)).length === 0;
+        return stillValid ? savedChanges : {};
+    }
+};
+exports.SettingsService = SettingsService;
+exports.SettingsService = SettingsService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(constants_1.AUTH_OPTIONS_TOKEN)),
+    __metadata("design:paramtypes", [Object])
+], SettingsService);
+//# sourceMappingURL=settings.service.js.map

package/dist/features/settings/settings.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.service.js","sourceRoot":"","sources":["../../../src/features/settings/settings.service.ts"],"names":[],"mappings":"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"}

package/dist/features/settings/settings.types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Everything an app (or an admin at runtime) can switch on, off or adjust.
+ * Defaults are in settings.defaults.ts; validation rules in settings.validation.ts.
+ */
+export interface AuthSettings {
+    registration: {
+        /** Allow new accounts at all (with any method). */
+        enabled: boolean;
+        /** Roles every new user gets, e.g. ["user"]. Users can never choose their own role. */
+        defaultRoles: string[];
+        requireFirstAndLastName: boolean;
+        /** Registration with email + password must also include a phone number. */
+        requirePhoneNumber: boolean;
+        requireTermsAcceptance: boolean;
+        requirePrivacyPolicyAcceptance: boolean;
+        /** Only these email domains may register, e.g. ["myapp.com"]. Empty = anyone. */
+        allowedEmailDomains: string[];
+    };
+    /** Which verifications move an account from PENDING_VERIFICATION to ACTIVE. */
+    activation: {
+        requireVerifiedEmail: boolean;
+        requireVerifiedPhone: boolean;
+    };
+    password: {
+        enabled: boolean;
+        minimumLength: number;
+        requireUppercaseLetter: boolean;
+        requireLowercaseLetter: boolean;
+        requireNumber: boolean;
+        requireSymbol: boolean;
+        /** Refuse passwords found in public data breaches (haveibeenpwned.com; the password never leaves your server). */
+        rejectBreachedPasswords: boolean;
+        /** Email the user when their password changes. */
+        notifyOnChange: boolean;
+    };
+    emailVerification: {
+        /** How long the "verify your email" link works. */
+        linkExpiresInHours: number;
+    };
+    passwordReset: {
+        /** How long the "reset your password" link works. */
+        linkExpiresInMinutes: number;
+    };
+    emailChange: {
+        /** How long the link that confirms a new email address works. */
+        linkExpiresInMinutes: number;
+    };
+    emailOtp: {
+        enabled: boolean;
+        codeLength: number;
+        expiresInMinutes: number;
+        /** Wait before another code can be sent to the same email. */
+        resendAfterSeconds: number;
+        /** Create an account when an unknown email signs in with a code. */
+        allowSignUp: boolean;
+    };
+    magicLink: {
+        enabled: boolean;
+        /** How long the sign-in link works. */
+        expiresInMinutes: number;
+        allowSignUp: boolean;
+    };
+    phoneOtp: {
+        enabled: boolean;
+        codeLength: number;
+        expiresInMinutes: number;
+        /** Wait before another code can be sent to the same number. */
+        resendAfterSeconds: number;
+        allowSignUp: boolean;
+        /** Country calling codes allowed, e.g. ["+91"]. Empty = any country. */
+        allowedCountryCodes: string[];
+    };
+    google: {
+        enabled: boolean;
+        /** OAuth client IDs of your apps (web, Android, iOS) from Google Cloud Console. */
+        clientIds: string[];
+    };
+    apple: {
+        enabled: boolean;
+        /** Your iOS bundle ID and/or web Services ID, e.g. ["com.myapp.ios"]. */
+        clientIds: string[];
+    };
+    facebook: {
+        enabled: boolean;
+        /** Your Facebook App ID (the secret goes in AuthOptions.facebookAppSecret). */
+        appId: string;
+    };
+    passkeys: {
+        enabled: boolean;
+    };
+    twoFactor: {
+        /** Users may turn on two-factor authentication with an authenticator app. */
+        enabled: boolean;
+        /** After the password (or code) is right, how long the user has to enter their 2FA code. */
+        challengeExpiresInMinutes: number;
+    };
+    organizations: {
+        enabled: boolean;
+        /** Any user may create an organization (otherwise only admins). */
+        allowUsersToCreate: boolean;
+        /** How long an emailed invitation can be accepted. */
+        invitationExpiresInDays: number;
+    };
+    tokens: {
+        accessTokenMinutes: number;
+        refreshTokenDays: number;
+        /** Hard limit: after this many days the user must sign in again. */
+        sessionDays: number;
+    };
+    admin: {
+        /** Users with any of these roles may use the /auth/admin endpoints. */
+        adminRoles: string[];
+    };
+    security: {
+        /** Email the user when their account is signed in from a new device. */
+        notifyOnNewSignIn: boolean;
+    };
+    /** How long old rows are kept. A cleanup runs every hour on each server (DataRetentionService). */
+    retention: {
+        /** Turn the automatic hourly cleanup off (e.g. to run it from your own job instead). */
+        enabled: boolean;
+        /** Ended sessions and used or expired codes, links, 2FA challenges and invitations. */
+        expiredRecordDays: number;
+        /** Delivered or failed webhook deliveries (pending ones are never removed). */
+        webhookDeliveryDays: number;
+        /** Audit log entries. 0 = keep forever. */
+        auditLogDays: number;
+    };
+}
+/** A partial set of settings: only the values you want to change. */
+export type SettingsChanges = {
+    [Section in keyof AuthSettings]?: Partial<AuthSettings[Section]>;
+};

package/dist/features/settings/settings.types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=settings.types.js.map

package/dist/features/settings/settings.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.types.js","sourceRoot":"","sources":["../../../src/features/settings/settings.types.ts"],"names":[],"mappings":""}

package/dist/features/settings/settings.validation.d.ts

@@ -0,0 +1,33 @@
+import { AuthSettings, SettingsChanges } from './settings.types';
+/**
+ * Checks a set of changes on its own (types, ranges, unknown fields).
+ *
+ * @param changes - Settings changes from code or from an admin.
+ * @returns Readable problems like "password.minimumLength must not be less than 8"; empty means valid.
+ */
+export declare function findProblemsInChanges(changes: unknown): string[];
+/**
+ * Checks rules that involve several settings together, on the final merged settings
+ * (e.g. at least one sign-in method must stay on).
+ *
+ * @param settings - The full merged settings.
+ * @returns Readable problems; empty means valid.
+ */
+export declare function findSettingsConflicts(settings: AuthSettings): string[];
+/**
+ * Applies changes on top of settings, one section at a time. Unknown sections are ignored.
+ * The input objects are not modified.
+ *
+ * @param base - The settings to start from.
+ * @param changes - The changes to apply.
+ * @returns A new settings object.
+ */
+export declare function applySettingsChanges(base: AuthSettings, changes?: SettingsChanges): AuthSettings;
+/**
+ * Combines two sets of changes; later values win. Used to keep admin changes on top of each other.
+ *
+ * @param earlier - The changes saved before.
+ * @param later - The new changes.
+ * @returns A new, combined set of changes.
+ */
+export declare function combineSettingsChanges(earlier: SettingsChanges, later: SettingsChanges): SettingsChanges;