auth-mn 0.2.0 → 1.0.0

package/README.md

@@ -1 +1,187 @@
-# AUTH.MN
+# auth-mn
+
+**Auth.mn** — таны апп-уудын нэгдсэн хэрэглэгчийн систем. Хэрэглэгч бүртгүүлэх, нэвтрэх
+(утас / имэйл OTP, Google, Facebook, Steam, QR), профайл, төхөөрөмж, мэдэгдлийг Auth.mn
+хариуцна; таны апп зөвхөн **хэрэглэгчийн token**-ийг хүлээж аваад Auth.mn-ээс мэдээллийг нь
+асууна.
+
+Энэ сан нь таны **backend (Node.js)** дээр ажиллана:
+
+| Та юу хийх вэ | Сангийн функц | Шаардлагатай эрх |
+|---|---|---|
+| Frontend-ээс ирсэн хэрэглэгчийн token шалгаж мэдээллийг авах | `user.verify(token)` / `user.middleware()` | `user.verify` |
+| user_id / утас / имэйлээр хэрэглэгч хайх | `user.find({...})` | `user.read` |
+| Push мэдэгдэл, SMS, имэйл илгээх | `notification.push / sms / mail` | `notification.*` |
+| Хэрэглэгчийн нээлттэй апп дээр realtime toast / төлөв харуулах | `socket.toast / status / orderStatus / emit` | `socket.*` |
+
+Frontend дээр нэвтрэх товч, QR нэвтрэлт хэрэгтэй бол **[auth-mn-react](https://www.npmjs.com/package/auth-mn-react)** санг хэрэглэнэ.
+
+```bash
+npm i auth-mn
+```
+
+---
+
+## 1. Client бүртгүүлэх
+
+Auth.mn **admin panel → Апп-ууд (Client)** дээр апп-аа бүртгэхэд `client_id` (`cl_…`) болон
+`client_secret` (`sk_…`) олгоно. Secret **нэг л удаа** харагдана — `.env`-дээ хадгална.
+Тухайн апп ямар API дуудаж болохыг (эрхүүдийг) admin тэндээ сонгоно; эрхгүй API дуудвал
+`403` + ямар эрх дутууг хэлсэн message ирнэ.
+
+```env
+AUTH_MN_CLIENT_ID=cl_xxxxxxxxxxxxxxxx
+AUTH_MN_CLIENT_SECRET=sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+## 2. Тохиргоо
+
+```ts
+import authMn, { setAuth, setHost } from "auth-mn";
+
+setHost("prod"); // "staging" эсвэл setHost({ MAIN: "https://api.auth.mn" })
+setAuth({
+  client_id: process.env.AUTH_MN_CLIENT_ID!,
+  client_secret: process.env.AUTH_MN_CLIENT_SECRET!
+});
+```
+
+Үүний дараа юу ч хийх шаардлагагүй: сан `client_id + secret`-ээр access token (1 цаг) болон
+refresh token (30 хоног) авч, хугацаа дуусахаас өмнө өөрөө сунгана. 401 ирвэл token-оо
+сэргээж нэг удаа дахин оролдоно. **Бүх функц `{ success, message, data, status }` буцна, throw хийхгүй.**
+
+## 3. Хэрэглэгч нэвтрүүлэх (гол урсгал)
+
+```
+[Frontend]  auth-mn-react → Auth.mn дээр нэвтэрнэ → таны сайт руу ?authToken=... буцна
+                 (эсвэл QR / OTP-оор token авна)
+      │  Authorization: Bearer <authToken>
+      ▼
+[Таны backend]  authMn.user.verify(authToken)  ──►  Auth.mn (client token + user.verify эрх)
+      │                                               token-ийг задалж, хэрэглэгчийн
+      ▼                                               мэдээллийг буцаана
+   өөрийн session / JWT үүсгэнэ, хэрэглэгчийг DB-дээ user_id-аар холбоно
+```
+
+### 3.1 Нэвтрэх endpoint
+
+```ts
+app.post("/api/auth/callback", async (req, res) => {
+  const v = await authMn.user.verify(req.body.authToken);
+  if (!v.success) return res.status(401).json({ message: v.message });
+
+  const u = v.data.user; // user_id, user_name, primary_phone, primary_email, profile_image_url, ...
+  // 1) өөрийн DB-д user_id-аар хайж байхгүй бол үүсгэнэ
+  // 2) өөрийн session / JWT үүсгэж cookie-д хадгална
+  res.json({ success: true, user: u });
+});
+```
+
+`v.data`:
+
+```ts
+{
+  user: UserT;                        // доорх бүтэц
+  exp: number | null;                 // хэрэглэгчийн token дуусах хугацаа (unix sec)
+  client: { client_id, name }         // ямар client-ээр шалгасан
+}
+```
+
+Шалгалт бүр хэрэглэгчийн **нэвтрэлтийн түүхэнд** "`<таны домэйн>`-д дамжуулсан" гэж бүртгэгдэнэ —
+хэрэглэгч Auth.mn дээрээ аль апп-д хэзээ нэвтэрснээ харна.
+
+### 3.2 Route хамгаалах middleware
+
+Хэрэглэгчийн token-ийг хүсэлт бүрт шалгах бол:
+
+```ts
+// Authorization: Bearer <token>  (эсвэл ?authToken= / body.authToken)
+app.get("/api/me", authMn.user.middleware(), (req, res) => {
+  res.json(req.authMnUser); // UserT
+});
+
+app.get("/api/feed", authMn.user.middleware({ required: false }), (req, res) => {
+  // нэвтрээгүй бол req.authMnUser === null, алдаа өгөхгүй
+});
+```
+
+> Хүсэлт бүрт Auth.mn руу нэг дуудлага хийдэг тул ачаалал ихтэй бол 3.1-ийн адил нэвтрэх үед нэг удаа
+> шалгаад өөрийн session/JWT ашиглахыг зөвлөнө.
+
+### 3.3 Хэрэглэгч хайх
+
+```ts
+const r = await authMn.user.find({ user_id: 5742248 });   // эсвэл { phone_number: "99112233" } / { email }
+if (r.success) console.log(r.data.user_name);
+```
+
+### UserT
+
+```ts
+{
+  user_id: number;              // Auth.mn-ийн тогтмол ID — өөрийн DB-д үүгээр холбоно
+  user_name: string;
+  nick_name: string;
+  primary_phone: string | null;
+  primary_email: string | null;
+  emails: { email, verified, primary }[];
+  phone_numbers: { number, verified, primary }[];
+  profile_image_url: string;
+  gender?: "MEN" | "WOMEN";
+  date_of_birth: Date | null;
+  auth_profiles: { google_id, facebook_id, steam_id, ... };
+  sign_up_date, last_login, ...
+}
+```
+
+## 4. Мэдэгдэл
+
+```ts
+await authMn.notification.push({
+  user_id: 5742248,
+  target_app: "MY-APP",
+  body: { title: "Захиалга", body: "Захиалга #123 батлагдлаа", button: { title: "Харах", url: "https://..." } }
+});                                                                             // notification.push
+await authMn.notification.sms({ to: "99112233", from: "MYAPP", text: "Код: 1234" }); // notification.sms
+await authMn.notification.mail({
+  type: "notification", to: ["a@b.mn"], subject: "Сайн уу",
+  body: { name: "Бат", title: "Тавтай морил", desc: "..." }
+});                                                                             // notification.mail
+```
+
+## 5. Socket (realtime)
+
+Хэрэглэгч Auth.mn-тэй холбогдсон аль нэг апп-аа нээлттэй байхад:
+
+```ts
+await authMn.socket.toast({ user_id, type: "info", text: "Төлбөр амжилттай" });          // socket.toast
+await authMn.socket.status({ user_id, id: "order-123", type: "Loading", title: "Боловсруулж байна" }); // socket.status
+await authMn.socket.status({ user_id, id: "order-123", type: "Success", title: "Амжилттай", amount: 15000 });
+await authMn.socket.orderStatus({ user_id, order_id: "order-123" });                      // socket.status
+await authMn.socket.emit([{ user_id, emit_name: "my-event", data: { any: 1 } }]);        // socket.emit
+```
+
+## 6. Client өөрийн мэдээлэл
+
+```ts
+await authMn.auth.me();                      // { client_id, name, permissions, ... }
+authMn.auth.hasPermission("notification.sms"); // сүүлийн token-оос
+await authMn.auth.permissions();             // Auth.mn-ийн бүх боломжит эрх
+await authMn.auth.revoke();                  // refresh token-оо хүчингүй болгоод cache цэвэрлэнэ
+```
+
+## Алдаа
+
+| status | Шалтгаан |
+|---|---|
+| 401 | client_id/secret буруу, client идэвхгүй, эсвэл хэрэглэгчийн token хүчингүй |
+| 403 | Энэ API-д шаардлагатай эрх client-д олгогдоогүй — admin panel дээр нэмнэ |
+| 0 | Сүлжээний алдаа (`message`-д шалтгаан) |
+
+## 0.x → 1.0 шилжилт
+
+- `config.auth.username / password`, `auth.TOKEN({username,password})` → `setAuth({ client_id, client_secret })`.
+  Хуучин client бүртгэлүүд admin panel дээр **Secret шинэчлэх** дарж secret авна.
+- `find.USER / MERCHANT / ADMIN / CLIENT / CRM` **хасагдсан** — хэрэглэгчийн мэдээлэл `user.verify` / `user.find`-ээр.
+- `notification.SinglePushNoti / SMS / MAIL`, `socket.ShowToast / ShowStatus / ShowOrderStatus / EMIT` хэвээр ажиллана (alias).
+- `notification._3RD.*` хасагдсан.

package/dist/auth.d.ts

@@ -1,8 +1,59 @@
+import { ClientInfo, PermissionGroup, Result, TokenData } from "./types";
+export declare class AuthState {
+    accessToken: string;
+    refreshToken: string;
+    /** ms epoch */
+    accessExpiresAt: number;
+    refreshExpiresAt: number;
+    permissions: string[];
+    lastError: string;
+    pending: Promise<string> | null;
+    get token(): string;
+    isAccessValid(): boolean;
+    isRefreshValid(): boolean;
+    apply(d: TokenData): void;
+    clear(): void;
+    /** Зэрэг олон хүсэлт ирэхэд нэг л удаа token авна */
+    single(fn: () => Promise<string>): Promise<string>;
+}
+export declare const authState: AuthState;
+/** client_id + client_secret → шинэ token хос */
+export declare const login: () => Promise<Result<TokenData>>;
+/** refresh_token → шинэ token хос (хуучин refresh хүчингүй болно) */
+export declare const refresh: () => Promise<Result<TokenData>>;
+/**
+ * Хүчинтэй access token буцаана (cache → refresh → login).
+ * Бусад бүх API функц үүнийг автоматаар дуудна.
+ */
 export declare const getToken: () => Promise<string>;
+/** Одоогийн refresh token-ийг серверт хүчингүй болгоод cache цэвэрлэнэ */
+export declare const revoke: () => Promise<Result<null>>;
+/** Client-ийн мэдээлэл + олгогдсон permission */
+export declare const me: () => Promise<Result<ClientInfo>>;
+/** Auth.mn-ийн бүх боломжит permission (public) */
+export declare const permissions: () => Promise<Result<PermissionGroup[]>>;
+/** Энэ client тухайн эрхтэй эсэх (сүүлийн token-оос) */
+export declare const hasPermission: (perm: string) => boolean;
+/**
+ * @deprecated v1.0.0-ээс: email/password-оор нэвтрэх боломжгүй болсон.
+ * setAuth({ client_id, client_secret }) ашиглана уу. Одоо getToken()-ийг дуудна.
+ */
+export declare const TOKEN: (_legacy?: {
+    username: string;
+    password: string;
+}) => Promise<string>;
 declare const _default: {
-    TOKEN: (auth: {
+    getToken: () => Promise<string>;
+    login: () => Promise<Result<TokenData>>;
+    refresh: () => Promise<Result<TokenData>>;
+    revoke: () => Promise<Result<null>>;
+    me: () => Promise<Result<ClientInfo>>;
+    permissions: () => Promise<Result<PermissionGroup[]>>;
+    hasPermission: (perm: string) => boolean;
+    TOKEN: (_legacy?: {
         username: string;
         password: string;
     }) => Promise<string>;
+    state: AuthState;
 };
 export default _default;

package/dist/auth.js

@@ -1,95 +1,147 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getToken = void 0;
-const _1 = require("./");
-const axios_master_1 = require("axios-master");
-const TOKEN = async (auth) => {
-    try {
-        const response = await (0, axios_master_1.axiosMasterLogger)({
-            method: "POST",
-            url: `${_1.config.hosts.MAIN}/main/v1/auth/client/login`,
-            headers: {
-                "Content-Type": "application/json"
-            },
-            data: {
-                email: auth.username,
-                password: auth.password
-            }
-        }, {
-            name: "Auth.mn Token",
-            timeout: 20000,
-            logger: (data) => {
-                if (_1.config.logger) {
-                    console.log({
-                        time: data.json.time,
-                        request: data.json.request,
-                        response: `${data.json.response}`,
-                        responseBody: data.json.responseBody,
-                        statusCode: data.json.statusCode
-                    });
-                }
-            }
-        });
-        if (response === null || response === void 0 ? void 0 : response.token) {
-            _1.config.token = response === null || response === void 0 ? void 0 : response.token;
-            return response === null || response === void 0 ? void 0 : response.token;
-        }
-        return "";
+exports.TOKEN = exports.hasPermission = exports.permissions = exports.me = exports.revoke = exports.getToken = exports.refresh = exports.login = exports.authState = exports.AuthState = void 0;
+const index_1 = require("./index");
+const request_1 = require("./request");
+/** Хугацаа дуусахаас хэдэн секундын өмнө refresh хийх */
+const REFRESH_MARGIN_SEC = 60;
+class AuthState {
+    constructor() {
+        this.accessToken = "";
+        this.refreshToken = "";
+        /** ms epoch */
+        this.accessExpiresAt = 0;
+        this.refreshExpiresAt = 0;
+        this.permissions = [];
+        this.lastError = "";
+        this.pending = null;
     }
-    catch (error) {
-        const axiosError = error;
-        if (axiosError.data) {
-            console.log(axiosError.data);
-        }
-        else {
-            console.error("Token Request Failed:", axiosError);
+    get token() {
+        return this.accessToken;
+    }
+    isAccessValid() {
+        return !!this.accessToken && Date.now() < this.accessExpiresAt - REFRESH_MARGIN_SEC * 1000;
+    }
+    isRefreshValid() {
+        return !!this.refreshToken && Date.now() < this.refreshExpiresAt - 5000;
+    }
+    apply(d) {
+        this.accessToken = d.access_token;
+        this.refreshToken = d.refresh_token;
+        this.accessExpiresAt = Date.now() + d.expires_in * 1000;
+        this.refreshExpiresAt = Date.now() + d.refresh_expires_in * 1000;
+        this.permissions = d.permissions || [];
+        this.lastError = "";
+    }
+    clear() {
+        this.accessToken = "";
+        this.refreshToken = "";
+        this.accessExpiresAt = 0;
+        this.refreshExpiresAt = 0;
+        this.permissions = [];
+    }
+    /** Зэрэг олон хүсэлт ирэхэд нэг л удаа token авна */
+    single(fn) {
+        if (!this.pending) {
+            this.pending = fn().finally(() => (this.pending = null));
         }
-        return "";
+        return this.pending;
+    }
+}
+exports.AuthState = AuthState;
+exports.authState = new AuthState();
+/** client_id + client_secret → шинэ token хос */
+const login = async () => {
+    var _a;
+    if (!index_1.config.auth.client_id || !index_1.config.auth.client_secret) {
+        exports.authState.lastError = "client_id / client_secret тохируулаагүй байна (setAuth).";
+        return { success: false, message: exports.authState.lastError, data: null, status: 0 };
     }
+    const res = await (0, request_1.rawRequest)({
+        method: "POST",
+        path: "/main/v1/auth/client/token",
+        name: "client token",
+        data: { client_id: index_1.config.auth.client_id, client_secret: index_1.config.auth.client_secret }
+    });
+    if (res.success && ((_a = res.data) === null || _a === void 0 ? void 0 : _a.access_token))
+        exports.authState.apply(res.data);
+    else
+        exports.authState.lastError = res.message;
+    return res;
 };
-const getToken = async () => {
-    try {
-        const response = await (0, axios_master_1.axiosMasterLogger)({
-            method: "POST",
-            url: `${_1.config.hosts.MAIN}/main/v1/auth/client/login`,
-            headers: {
-                "Content-Type": "application/json"
-            },
-            data: {
-                email: _1.config.auth.username,
-                password: _1.config.auth.password
-            }
-        }, {
-            name: "Auth.mn Token",
-            timeout: 20000,
-            logger: (data) => {
-                if (_1.config.logger) {
-                    console.log({
-                        time: data.json.time,
-                        request: data.json.request,
-                        response: `${data.json.response}`,
-                        responseBody: data.json.responseBody,
-                        statusCode: data.json.statusCode
-                    });
-                }
-            }
-        });
-        if (response === null || response === void 0 ? void 0 : response.token) {
-            _1.config.token = response === null || response === void 0 ? void 0 : response.token;
-            return response === null || response === void 0 ? void 0 : response.token;
-        }
-        return "";
+exports.login = login;
+/** refresh_token → шинэ token хос (хуучин refresh хүчингүй болно) */
+const refresh = async () => {
+    var _a;
+    if (!exports.authState.isRefreshValid()) {
+        return { success: false, message: "refresh token алга эсвэл хугацаа дууссан", data: null, status: 0 };
     }
-    catch (error) {
-        const axiosError = error;
-        if (axiosError.data) {
-            console.log(axiosError.data);
-        }
-        else {
-            console.error("Token Request Failed:", axiosError);
-        }
-        return "";
+    const res = await (0, request_1.rawRequest)({
+        method: "POST",
+        path: "/main/v1/auth/client/token/refresh",
+        name: "client token refresh",
+        data: { refresh_token: exports.authState.refreshToken }
+    });
+    if (res.success && ((_a = res.data) === null || _a === void 0 ? void 0 : _a.access_token))
+        exports.authState.apply(res.data);
+    else {
+        exports.authState.clear();
+        exports.authState.lastError = res.message;
     }
+    return res;
 };
+exports.refresh = refresh;
+/**
+ * Хүчинтэй access token буцаана (cache → refresh → login).
+ * Бусад бүх API функц үүнийг автоматаар дуудна.
+ */
+const getToken = () => exports.authState.single(async () => {
+    if (exports.authState.isAccessValid())
+        return exports.authState.accessToken;
+    if (exports.authState.isRefreshValid()) {
+        const r = await (0, exports.refresh)();
+        if (r.success)
+            return exports.authState.accessToken;
+    }
+    const l = await (0, exports.login)();
+    return l.success ? exports.authState.accessToken : "";
+});
 exports.getToken = getToken;
-exports.default = { TOKEN };
+/** Одоогийн refresh token-ийг серверт хүчингүй болгоод cache цэвэрлэнэ */
+const revoke = async () => {
+    const rt = exports.authState.refreshToken;
+    exports.authState.clear();
+    if (!rt)
+        return { success: true, message: "token алга", data: null };
+    return (0, request_1.rawRequest)({
+        method: "POST",
+        path: "/main/v1/auth/client/token/revoke",
+        name: "client token revoke",
+        data: { refresh_token: rt }
+    });
+};
+exports.revoke = revoke;
+/** Client-ийн мэдээлэл + олгогдсон permission */
+const me = () => (0, request_1.request)({ method: "GET", path: "/main/v1/auth/client/me", name: "client me" });
+exports.me = me;
+/** Auth.mn-ийн бүх боломжит permission (public) */
+const permissions = () => (0, request_1.rawRequest)({ method: "GET", path: "/main/v1/auth/client/permissions", name: "permissions" });
+exports.permissions = permissions;
+/** Энэ client тухайн эрхтэй эсэх (сүүлийн token-оос) */
+const hasPermission = (perm) => {
+    const p = exports.authState.permissions;
+    return p.includes("*") || p.includes(perm) || p.includes(`${perm.split(".")[0]}.*`);
+};
+exports.hasPermission = hasPermission;
+/**
+ * @deprecated v1.0.0-ээс: email/password-оор нэвтрэх боломжгүй болсон.
+ * setAuth({ client_id, client_secret }) ашиглана уу. Одоо getToken()-ийг дуудна.
+ */
+const TOKEN = async (_legacy) => {
+    if (_legacy && index_1.config.logger) {
+        console.warn("[auth-mn] auth.TOKEN({username,password}) хуучирсан — setAuth({ client_id, client_secret }) ашиглана уу.");
+    }
+    return (0, exports.getToken)();
+};
+exports.TOKEN = TOKEN;
+exports.default = { getToken: exports.getToken, login: exports.login, refresh: exports.refresh, revoke: exports.revoke, me: exports.me, permissions: exports.permissions, hasPermission: exports.hasPermission, TOKEN: exports.TOKEN, state: exports.authState };