@awesome-lang-auth/node 1.10.1

package/dist/strategies/oauth/generic-oauth.strategy.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GenericOAuthStrategy = void 0;
+const base_oauth_strategy_abstract_1 = require("../../abstract/base-oauth-strategy.abstract");
+const errors_1 = require("../../models/errors");
+/**
+ * Generic OAuth 2.0 strategy.
+ *
+ * Extend this class to add OAuth login support for any provider that
+ * follows the standard Authorization Code flow with a JSON user-info
+ * endpoint.  Only `findOrCreateUser` needs to be implemented.
+ *
+ * @example
+ * ```typescript
+ * class MicrosoftStrategy extends GenericOAuthStrategy<MyUser> {
+ *   async findOrCreateUser(profile) {
+ *     let user = await userStore.findByProviderAccount('microsoft', profile.id);
+ *     if (!user) user = await userStore.create({ email: profile.email, loginProvider: 'microsoft' });
+ *     return user as MyUser;
+ *   }
+ * }
+ * ```
+ */
+class GenericOAuthStrategy extends base_oauth_strategy_abstract_1.BaseOAuthStrategy {
+    constructor(config) {
+        super();
+        this.name = config.name;
+        this.config = config;
+    }
+    getAuthorizationUrl(state) {
+        const scope = Array.isArray(this.config.scope)
+            ? this.config.scope.join(' ')
+            : this.config.scope;
+        const params = new URLSearchParams({
+            client_id: this.config.clientId,
+            redirect_uri: this.config.callbackUrl,
+            response_type: 'code',
+            scope,
+            ...this.config.additionalAuthParams,
+            ...(state ? { state } : {}),
+        });
+        return `${this.config.authorizationUrl}?${params.toString()}`;
+    }
+    async exchangeCodeForTokens(code) {
+        const res = await fetch(this.config.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+            body: new URLSearchParams({
+                code,
+                client_id: this.config.clientId,
+                client_secret: this.config.clientSecret,
+                redirect_uri: this.config.callbackUrl,
+                grant_type: 'authorization_code',
+            }).toString(),
+        });
+        if (!res.ok) {
+            throw new errors_1.AuthError(`${this.name} token exchange failed`, 'OAUTH_TOKEN_EXCHANGE_FAILED', 401);
+        }
+        const data = await res.json();
+        return { accessToken: data.access_token, idToken: data.id_token };
+    }
+    async getUserProfile(accessToken) {
+        const res = await fetch(this.config.userInfoUrl, {
+            headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
+        });
+        if (!res.ok) {
+            throw new errors_1.AuthError(`Failed to get ${this.name} user profile`, 'OAUTH_PROFILE_FAILED', 401);
+        }
+        const raw = await res.json();
+        if (this.config.mapProfile) {
+            return this.config.mapProfile(raw);
+        }
+        return {
+            id: String(raw['id'] ?? raw['sub'] ?? ''),
+            email: String(raw['email'] ?? ''),
+            emailVerified: raw['email_verified'],
+            name: raw['name'],
+            picture: raw['picture'],
+        };
+    }
+    async handleCallback(code, state) {
+        const { accessToken } = await this.exchangeCodeForTokens(code);
+        const profile = await this.getUserProfile(accessToken);
+        return this.findOrCreateUser(profile, state);
+    }
+}
+exports.GenericOAuthStrategy = GenericOAuthStrategy;
+//# sourceMappingURL=generic-oauth.strategy.js.map

package/dist/strategies/oauth/generic-oauth.strategy.js.map

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

package/dist/strategies/oauth/github.strategy.d.ts

@@ -0,0 +1,31 @@
+import { BaseOAuthStrategy } from '../../abstract/base-oauth-strategy.abstract';
+import { BaseUser } from '../../models/user.model';
+import { AuthConfig } from '../../models/auth-config.model';
+export declare abstract class GithubStrategy<TUser extends BaseUser = BaseUser> extends BaseOAuthStrategy<TUser> {
+    name: string;
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly callbackUrl;
+    constructor(config: AuthConfig);
+    getAuthorizationUrl(state?: string): string;
+    protected exchangeCodeForTokens(code: string): Promise<{
+        accessToken: string;
+        idToken?: string;
+    }>;
+    protected getUserProfile(accessToken: string): Promise<{
+        id: string;
+        email: string;
+        emailVerified?: boolean;
+        name?: string;
+        picture?: string;
+    }>;
+    handleCallback(code: string, state?: string): Promise<TUser>;
+    abstract findOrCreateUser(profile: {
+        id: string;
+        email: string;
+        emailVerified?: boolean;
+        name?: string;
+        picture?: string;
+    }, state?: string): Promise<TUser>;
+}
+//# sourceMappingURL=github.strategy.d.ts.map

package/dist/strategies/oauth/github.strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.strategy.d.ts","sourceRoot":"","sources":["../../../src/strategies/oauth/github.strategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAG5D,8BAAsB,cAAc,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,CAAE,SAAQ,iBAAiB,CAAC,KAAK,CAAC;IACtG,IAAI,SAAY;IAEhB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,MAAM,EAAE,UAAU;IAU9B,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;cAU3B,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;cAgBvF,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAuB/I,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAMlE,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;CAC5J"}

package/dist/strategies/oauth/github.strategy.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GithubStrategy = void 0;
+const base_oauth_strategy_abstract_1 = require("../../abstract/base-oauth-strategy.abstract");
+const errors_1 = require("../../models/errors");
+class GithubStrategy extends base_oauth_strategy_abstract_1.BaseOAuthStrategy {
+    constructor(config) {
+        super();
+        this.name = 'github';
+        if (!config.oauth?.github) {
+            throw new errors_1.AuthError('GitHub OAuth not configured', 'OAUTH_NOT_CONFIGURED', 500);
+        }
+        this.clientId = config.oauth.github.clientId;
+        this.clientSecret = config.oauth.github.clientSecret;
+        this.callbackUrl = config.oauth.github.callbackUrl;
+    }
+    getAuthorizationUrl(state) {
+        const params = new URLSearchParams({
+            client_id: this.clientId,
+            redirect_uri: this.callbackUrl,
+            scope: 'user:email',
+            ...(state ? { state } : {}),
+        });
+        return `https://github.com/login/oauth/authorize?${params.toString()}`;
+    }
+    async exchangeCodeForTokens(code) {
+        const res = await fetch('https://github.com/login/oauth/access_token', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+            body: JSON.stringify({
+                client_id: this.clientId,
+                client_secret: this.clientSecret,
+                code,
+                redirect_uri: this.callbackUrl,
+            }),
+        });
+        if (!res.ok)
+            throw new errors_1.AuthError('GitHub token exchange failed', 'OAUTH_TOKEN_EXCHANGE_FAILED', 401);
+        const data = await res.json();
+        return { accessToken: data.access_token };
+    }
+    async getUserProfile(accessToken) {
+        const [userRes, emailRes] = await Promise.all([
+            fetch('https://api.github.com/user', {
+                headers: { Authorization: `token ${accessToken}`, Accept: 'application/vnd.github.v3+json' },
+            }),
+            fetch('https://api.github.com/user/emails', {
+                headers: { Authorization: `token ${accessToken}`, Accept: 'application/vnd.github.v3+json' },
+            }),
+        ]);
+        if (!userRes.ok)
+            throw new errors_1.AuthError('Failed to get GitHub user profile', 'OAUTH_PROFILE_FAILED', 401);
+        const user = await userRes.json();
+        let email = user.email ?? '';
+        let emailVerified;
+        if (!email && emailRes.ok) {
+            const emails = await emailRes.json();
+            const primary = emails.find(e => e.primary && e.verified);
+            const primaryEntry = primary ?? emails[0];
+            email = primaryEntry?.email ?? '';
+            emailVerified = primaryEntry?.verified;
+        }
+        return { id: String(user.id), email, emailVerified, name: user.name ?? user.login, picture: user.avatar_url };
+    }
+    async handleCallback(code, state) {
+        const { accessToken } = await this.exchangeCodeForTokens(code);
+        const profile = await this.getUserProfile(accessToken);
+        return this.findOrCreateUser(profile, state);
+    }
+}
+exports.GithubStrategy = GithubStrategy;
+//# sourceMappingURL=github.strategy.js.map

package/dist/strategies/oauth/github.strategy.js.map

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

package/dist/strategies/oauth/google.strategy.d.ts

@@ -0,0 +1,31 @@
+import { BaseOAuthStrategy } from '../../abstract/base-oauth-strategy.abstract';
+import { BaseUser } from '../../models/user.model';
+import { AuthConfig } from '../../models/auth-config.model';
+export declare abstract class GoogleStrategy<TUser extends BaseUser = BaseUser> extends BaseOAuthStrategy<TUser> {
+    name: string;
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly callbackUrl;
+    constructor(config: AuthConfig);
+    getAuthorizationUrl(state?: string): string;
+    protected exchangeCodeForTokens(code: string): Promise<{
+        accessToken: string;
+        idToken?: string;
+    }>;
+    protected getUserProfile(accessToken: string): Promise<{
+        id: string;
+        email: string;
+        emailVerified?: boolean;
+        name?: string;
+        picture?: string;
+    }>;
+    handleCallback(code: string, state?: string): Promise<TUser>;
+    abstract findOrCreateUser(profile: {
+        id: string;
+        email: string;
+        emailVerified?: boolean;
+        name?: string;
+        picture?: string;
+    }, state?: string): Promise<TUser>;
+}
+//# sourceMappingURL=google.strategy.d.ts.map

package/dist/strategies/oauth/google.strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google.strategy.d.ts","sourceRoot":"","sources":["../../../src/strategies/oauth/google.strategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAG5D,8BAAsB,cAAc,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,CAAE,SAAQ,iBAAiB,CAAC,KAAK,CAAC;IACtG,IAAI,SAAY;IAEhB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,MAAM,EAAE,UAAU;IAU9B,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;cAY3B,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;cAiBvF,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAS/I,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAMlE,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;CAC5J"}

package/dist/strategies/oauth/google.strategy.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoogleStrategy = void 0;
+const base_oauth_strategy_abstract_1 = require("../../abstract/base-oauth-strategy.abstract");
+const errors_1 = require("../../models/errors");
+class GoogleStrategy extends base_oauth_strategy_abstract_1.BaseOAuthStrategy {
+    constructor(config) {
+        super();
+        this.name = 'google';
+        if (!config.oauth?.google) {
+            throw new errors_1.AuthError('Google OAuth not configured', 'OAUTH_NOT_CONFIGURED', 500);
+        }
+        this.clientId = config.oauth.google.clientId;
+        this.clientSecret = config.oauth.google.clientSecret;
+        this.callbackUrl = config.oauth.google.callbackUrl;
+    }
+    getAuthorizationUrl(state) {
+        const params = new URLSearchParams({
+            client_id: this.clientId,
+            redirect_uri: this.callbackUrl,
+            response_type: 'code',
+            scope: 'openid email profile',
+            access_type: 'offline',
+            ...(state ? { state } : {}),
+        });
+        return `https://accounts.google.com/o/oauth2/v2/auth?${params.toString()}`;
+    }
+    async exchangeCodeForTokens(code) {
+        const res = await fetch('https://oauth2.googleapis.com/token', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                code,
+                client_id: this.clientId,
+                client_secret: this.clientSecret,
+                redirect_uri: this.callbackUrl,
+                grant_type: 'authorization_code',
+            }).toString(),
+        });
+        if (!res.ok)
+            throw new errors_1.AuthError('Google token exchange failed', 'OAUTH_TOKEN_EXCHANGE_FAILED', 401);
+        const data = await res.json();
+        return { accessToken: data.access_token, idToken: data.id_token };
+    }
+    async getUserProfile(accessToken) {
+        const res = await fetch('https://www.googleapis.com/oauth2/v3/userinfo', {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+        if (!res.ok)
+            throw new errors_1.AuthError('Failed to get Google user profile', 'OAUTH_PROFILE_FAILED', 401);
+        const data = await res.json();
+        return { id: data.sub, email: data.email, emailVerified: data.email_verified, name: data.name, picture: data.picture };
+    }
+    async handleCallback(code, state) {
+        const { accessToken } = await this.exchangeCodeForTokens(code);
+        const profile = await this.getUserProfile(accessToken);
+        return this.findOrCreateUser(profile, state);
+    }
+}
+exports.GoogleStrategy = GoogleStrategy;
+//# sourceMappingURL=google.strategy.js.map

package/dist/strategies/oauth/google.strategy.js.map

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

package/dist/strategies/sms/sms.strategy.d.ts

@@ -0,0 +1,7 @@
+import { IUserStore } from '../../interfaces/user-store.interface';
+import { AuthConfig } from '../../models/auth-config.model';
+export declare class SmsStrategy {
+    sendCode(phone: string, userId: string, userStore: IUserStore, config: AuthConfig): Promise<void>;
+    verify(userId: string, code: string, userStore: IUserStore): Promise<boolean>;
+}
+//# sourceMappingURL=sms.strategy.d.ts.map

package/dist/strategies/sms/sms.strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sms.strategy.d.ts","sourceRoot":"","sources":["../../../src/strategies/sms/sms.strategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAO5D,qBAAa,WAAW;IAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAajG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CAcpF"}

package/dist/strategies/sms/sms.strategy.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SmsStrategy = void 0;
+const sms_service_1 = require("../../services/sms.service");
+const password_service_1 = require("../../services/password.service");
+const errors_1 = require("../../models/errors");
+const passwordService = new password_service_1.PasswordService();
+class SmsStrategy {
+    async sendCode(phone, userId, userStore, config) {
+        if (!config.sms) {
+            throw new errors_1.AuthError('SMS not configured', 'SMS_NOT_CONFIGURED', 500);
+        }
+        const smsService = new sms_service_1.SmsService(config.sms);
+        const code = smsService.generateCode();
+        const hashedCode = await passwordService.hash(code, 10);
+        const expiresInMin = config.sms.codeExpiresInMinutes ?? 10;
+        const expiry = new Date(Date.now() + expiresInMin * 60 * 1000);
+        await userStore.updateSmsCode(userId, hashedCode, expiry);
+        await smsService.sendSms(phone, `Your verification code is: ${code}`);
+    }
+    async verify(userId, code, userStore) {
+        const user = await userStore.findById(userId);
+        if (!user)
+            return false;
+        if (!user.smsCode)
+            return false;
+        if (user.smsCodeExpiry && new Date() > user.smsCodeExpiry) {
+            await userStore.updateSmsCode(userId, null, null);
+            return false;
+        }
+        const valid = await passwordService.compare(code, user.smsCode);
+        if (valid) {
+            await userStore.updateSmsCode(userId, null, null);
+        }
+        return valid;
+    }
+}
+exports.SmsStrategy = SmsStrategy;
+//# sourceMappingURL=sms.strategy.js.map

package/dist/strategies/sms/sms.strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sms.strategy.js","sourceRoot":"","sources":["../../../src/strategies/sms/sms.strategy.ts"],"names":[],"mappings":";;;AAEA,4DAAwD;AACxD,sEAAkE;AAClE,gDAAgD;AAEhD,MAAM,eAAe,GAAG,IAAI,kCAAe,EAAE,CAAC;AAE9C,MAAa,WAAW;IACtB,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,MAAc,EAAE,SAAqB,EAAE,MAAkB;QACrF,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;YAChB,MAAM,IAAI,kBAAS,CAAC,oBAAoB,EAAE,oBAAoB,EAAE,GAAG,CAAC,CAAC;QACvE,CAAC;QACD,MAAM,UAAU,GAAG,IAAI,wBAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,YAAY,EAAE,CAAC;QACvC,MAAM,UAAU,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACxD,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,oBAAoB,IAAI,EAAE,CAAC;QAC3D,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC/D,MAAM,SAAS,CAAC,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;QAC1D,MAAM,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,8BAA8B,IAAI,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,IAAY,EAAE,SAAqB;QAC9D,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QACxB,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAChC,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,IAAI,EAAE,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YAC1D,MAAM,SAAS,CAAC,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YAClD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAChE,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,SAAS,CAAC,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACpD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF;AA5BD,kCA4BC"}

package/dist/strategies/two-factor/totp.strategy.d.ts

@@ -0,0 +1,12 @@
+import { IUserStore } from '../../interfaces/user-store.interface';
+export declare class TotpStrategy {
+    generateSecret(email: string, appName?: string): {
+        secret: string;
+        otpauthUrl: string;
+        qrCode: Promise<string>;
+    };
+    verify(token: string, secret: string): Promise<boolean>;
+    enable(userId: string, secret: string, userStore: IUserStore): Promise<void>;
+    disable(userId: string, userStore: IUserStore): Promise<void>;
+}
+//# sourceMappingURL=totp.strategy.d.ts.map

package/dist/strategies/two-factor/totp.strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp.strategy.d.ts","sourceRoot":"","sources":["../../../src/strategies/two-factor/totp.strategy.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AAOnE,qBAAa,YAAY;IACvB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,MAA4B,GAAG;QACpE,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;KACzB;IAOK,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKvD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5E,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAGpE"}

package/dist/strategies/two-factor/totp.strategy.js

@@ -0,0 +1,32 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TotpStrategy = void 0;
+const otplib_1 = require("otplib");
+const qrcode_1 = __importDefault(require("qrcode"));
+const totp = new otplib_1.TOTP({
+    crypto: new otplib_1.NobleCryptoPlugin(),
+    base32: new otplib_1.ScureBase32Plugin(),
+});
+class TotpStrategy {
+    generateSecret(email, appName = 'awesome-node-auth') {
+        const secret = totp.generateSecret();
+        const otpauthUrl = totp.toURI({ label: email, issuer: appName, secret });
+        const qrCode = qrcode_1.default.toDataURL(otpauthUrl);
+        return { secret, otpauthUrl, qrCode };
+    }
+    async verify(token, secret) {
+        const result = await totp.verify(token, { secret });
+        return result.valid;
+    }
+    async enable(userId, secret, userStore) {
+        await userStore.updateTotpSecret(userId, secret);
+    }
+    async disable(userId, userStore) {
+        await userStore.updateTotpSecret(userId, null);
+    }
+}
+exports.TotpStrategy = TotpStrategy;
+//# sourceMappingURL=totp.strategy.js.map

package/dist/strategies/two-factor/totp.strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp.strategy.js","sourceRoot":"","sources":["../../../src/strategies/two-factor/totp.strategy.ts"],"names":[],"mappings":";;;;;;AAAA,mCAAoE;AACpE,oDAA4B;AAG5B,MAAM,IAAI,GAAG,IAAI,aAAI,CAAC;IACpB,MAAM,EAAE,IAAI,0BAAiB,EAAE;IAC/B,MAAM,EAAE,IAAI,0BAAiB,EAAE;CAChC,CAAC,CAAC;AAEH,MAAa,YAAY;IACvB,cAAc,CAAC,KAAa,EAAE,UAAkB,mBAAmB;QAKjE,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QACrC,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QACzE,MAAM,MAAM,GAAG,gBAAM,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAC5C,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,MAAc;QACxC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QACpD,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,MAAc,EAAE,SAAqB;QAChE,MAAM,SAAS,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnD,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,SAAqB;QACjD,MAAM,SAAS,CAAC,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACjD,CAAC;CACF;AAxBD,oCAwBC"}

package/dist/tools/auth-tools.d.ts

@@ -0,0 +1,200 @@
+import { AuthEventBus } from '../events/auth-event-bus';
+import { ITelemetryStore } from '../interfaces/telemetry-store.interface';
+import { IWebhookStore } from '../interfaces/webhook-store.interface';
+import { ISseDistributor } from '../interfaces/sse-distributor.interface';
+import { IUserStore } from '../interfaces/user-store.interface';
+import { SseManager } from './sse-manager';
+import { EmailNotificationConfig, SmsNotificationConfig } from '../services/notification.service';
+/**
+ * Options passed to {@link AuthTools}.
+ */
+export interface AuthToolsOptions {
+    /**
+     * Optional telemetry store.  When provided, every tracked event is also
+     * persisted via `store.save()`.
+     */
+    telemetryStore?: ITelemetryStore;
+    /**
+     * Optional webhook store.  When provided, outgoing webhooks are dispatched
+     * whenever an event is tracked.
+     */
+    webhookStore?: IWebhookStore;
+    /**
+     * When `true`, SSE streaming is enabled.  A `SseManager` instance will be
+     * created and the `/tools/stream` endpoint will be available.
+     * @default false
+     */
+    sse?: boolean;
+    /**
+     * Options forwarded to the `SseManager` constructor.
+     */
+    sseOptions?: {
+        /** @default 30000 */
+        heartbeatIntervalMs?: number;
+        /** Distributor for cross-instance event synchronization. */
+        distributor?: ISseDistributor;
+        /** @default true */
+        deduplicate?: boolean;
+    };
+    /**
+     * Optional custom SSE distributor for AuthTools.notify().
+     * When provided it is used instead of the internal SseManager broadcaster.
+     */
+    sseDistributor?: ISseDistributor;
+    /**
+     * Semantic version string attached to all outgoing webhook payloads.
+     * @default '1'
+     */
+    webhookVersion?: string;
+    /**
+     * Optional user store.  Required when using `'email'` or `'sms'` channels
+     * in {@link AuthTools.notify} so the service can look up the user's contact
+     * details by `options.userId`.
+     *
+     * @since 1.8.0
+     */
+    userStore?: IUserStore;
+    /**
+     * Email transport configuration.  When provided, the `'email'` channel in
+     * {@link AuthTools.notify} will send emails using the built-in HTTP mailer.
+     *
+     * Accepts the same shape as `AuthConfig.email.mailer`.
+     *
+     * @since 1.8.0
+     */
+    emailConfig?: EmailNotificationConfig;
+    /**
+     * SMS transport configuration.  When provided, the `'sms'` channel in
+     * {@link AuthTools.notify} will send SMS messages using the built-in SMS
+     * service.
+     *
+     * Accepts the same shape as `AuthConfig.sms`.
+     *
+     * @since 1.8.0
+     */
+    smsConfig?: SmsNotificationConfig;
+}
+/**
+ * Options for {@link AuthTools.track}.
+ */
+export interface TrackOptions {
+    userId?: string;
+    tenantId?: string;
+    sessionId?: string;
+    correlationId?: string;
+    ip?: string;
+    userAgent?: string;
+}
+/**
+ * Options for {@link AuthTools.notify}.
+ */
+export interface NotifyOptions {
+    type?: string;
+    tenantId?: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+    /**
+     * Delivery channels.  Defaults to `['sse']` (backward-compatible).
+     *
+     * - `'sse'`   — broadcast to SSE subscribers on the given `target` topic.
+     * - `'email'` — send an email to the user identified by `userId` (requires
+     *               `userStore` and `emailConfig` in {@link AuthToolsOptions}).
+     * - `'sms'`   — send an SMS to the user identified by `userId` (requires
+     *               `userStore` and `smsConfig` in {@link AuthToolsOptions}).
+     *
+     * When multiple channels are listed, all are attempted; a failure in one
+     * channel does **not** abort the others.
+     *
+     * @since 1.8.0
+     * @default ['sse']
+     */
+    channels?: Array<'sse' | 'email' | 'sms'>;
+    /**
+     * Email subject override.  Used when `channels` includes `'email'`.
+     * Defaults to the stringified `options.type` or `'Notification'`.
+     *
+     * @since 1.8.0
+     */
+    emailSubject?: string;
+    /**
+     * SMS message body override.  Used when `channels` includes `'sms'`.
+     * Defaults to the JSON-stringified `data` payload.
+     *
+     * @since 1.8.0
+     */
+    smsMessage?: string;
+}
+/**
+ * The main tools module.
+ *
+ * Provides a unified API for telemetry tracking, real-time SSE notifications,
+ * and outgoing webhooks.  All capabilities are optional and have zero overhead
+ * when disabled.
+ *
+ * ```ts
+ * import { AuthTools, AuthEventBus } from '@awesome-lang-auth/node';
+ *
+ * const bus = new AuthEventBus();
+ * const tools = new AuthTools(bus, {
+ *   telemetryStore: myStore,
+ *   webhookStore: myWebhookStore,
+ *   sse: true,
+ * });
+ *
+ * // Track an event programmatically
+ * await tools.track('identity.auth.login.success', { user }, { userId: user.id });
+ *
+ * // Notify a topic over SSE
+ * await tools.notify('user:123', { message: 'Welcome!' });
+ * ```
+ */
+export declare class AuthTools {
+    readonly eventBus: AuthEventBus;
+    readonly sseManager: SseManager | null;
+    private readonly telemetryStore?;
+    private readonly webhookStore?;
+    private readonly webhookSender;
+    private readonly webhookVersion;
+    private readonly userStore?;
+    private readonly notificationService?;
+    private readonly sseDistributor?;
+    constructor(eventBus: AuthEventBus, options?: AuthToolsOptions);
+    /**
+     * Track an event: persist it (optional), emit it on the event bus, broadcast
+     * it to SSE subscribers and fire matching outgoing webhooks.
+     *
+     * @param eventName  Standardised event name (see `AuthEventNames`).
+     * @param data       Arbitrary event data.
+     * @param options    Metadata (userId, tenantId, …).
+     */
+    track(eventName: string, data?: unknown, options?: TrackOptions): Promise<void>;
+    /**
+     * Send a notification to one or more delivery channels.
+     *
+     * By default (or when `channels` is `['sse']`) the behaviour is identical to
+     * the original synchronous broadcast.  Pass additional channels to also
+     * deliver the notification via email and/or SMS.
+     *
+     * When `'email'` or `'sms'` is included the method becomes asynchronous and
+     * requires:
+     *   - `userStore` — to look up the user's contact details by `options.userId`.
+     *   - `emailConfig` / `smsConfig` — transport configuration in
+     *     {@link AuthToolsOptions}.
+     *
+     * Channel failures are best-effort and do not reject the returned Promise.
+     *
+     * @param target   Target SSE topic (e.g. `'user:123'`, `'tenant:acme'`).
+     * @param data     Payload to deliver.
+     * @param options  Channels, type, tenantId, userId, metadata, etc.
+     *
+     * @since 1.8.0 (async + multi-channel)
+     */
+    notify<T = unknown>(target: string, data: T, options?: NotifyOptions): Promise<void>;
+    /**
+     * Resolve the SSE topics an event should be broadcast to.
+     * Always includes `'global'`; additionally adds tenant and user topics when
+     * the corresponding IDs are present.
+     */
+    private resolveTopics;
+}
+//# sourceMappingURL=auth-tools.d.ts.map

package/dist/tools/auth-tools.d.ts.map

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