@things-factory/auth-base 10.1.3 → 10.1.6

package/dist-server/utils/account-lock-rule.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 계정 잠금이 아직 유효한지를 판정하는 규칙 (순수 함수).
+ *
+ * ## 왜 따로 있나
+ *
+ * 잠금을 보는 자리가 둘이다 — `signin`(들어오려는 사람)과 `User.checkAuth`(요청마다 토큰을
+ * 확인하는 자리). 두 곳이 각자 「아직 잠겼나」를 판단하면 서로 다른 답을 낼 수 있고, 그러면
+ * 로그인은 되는데 요청은 거절되는(또는 그 반대) 상태가 생긴다. 판정은 한 곳에 둔다
+ * (`checkin-domain-rule` 과 같은 규율).
+ *
+ * ## 자동해제를 주기 작업으로 하지 않는 이유
+ *
+ * 계정이 10만이면 「만료된 잠금을 풀어 주는 일」이 따로 일이 된다. 잠금은 **읽는 시점에**
+ * 판정한다 — 그 계정을 보는 사람이 있을 때만 계산하면 되고, 그때가 유일하게 답이 필요한
+ * 순간이다.
+ *
+ * 행을 정리하는 것은 판정과 별개다. `signin` 은 판정이 「풀렸다」로 나오면 그 자리에서 행을
+ * 되돌리고(`ACTIVATED` · `failCount` 0 · `lockedAt` 비움) 계속 진행한다. `checkAuth` 는
+ * 매 요청 경로이므로 **읽기만 한다** — 판정만 보고 통과시키고, 행 정리는 다음 `signin` 이 한다.
+ *
+ * ## 잠금이 곧 셈의 창이다
+ *
+ * 자동해제 때 `failCount` 를 0 으로 두므로, 실패 셈은 「한 번의 잠금 안에서」만 쌓인다.
+ * 그래서 칸을 하나만 더해도 창이 생긴다.
+ *
+ * 남는 것: 잠기지 **않은** 동안의 셈은 여전히 누적이다(성공하면 0 으로 돌아간다). 그래서 오타를
+ * 드물게 다섯 번 내는 사람은 한 번 잠긴다 — 그 뒤 자동으로 풀리므로 견딜 수 있지만, 창을
+ * 정확히 하려면 「실패가 시작된 시각」 칸이 하나 더 필요하다.
+ */
+/** 판정에 필요한 사용자 측 사실들 — 조회는 부르는 쪽이 한다. */
+export type AccountLockFacts = {
+    /** `UserStatus` 값. `'locked'` 가 아니면 잠금이 아니다. */
+    status?: string | null;
+    /** 잠긴 시각. 이 변경 전에 잠긴 행에는 없다. */
+    lockedAt?: Date | string | null;
+};
+/** 잠금이 풀리지 않는 설정값 — 0 이하는 「자동해제 없음」이다. */
+export declare const LOCK_FOREVER = 0;
+/**
+ * `UserStatus.LOCKED` 의 값.
+ *
+ * 엔티티를 import 하지 않는다 — 그러면 이 모듈이 type-graphql 데코레이터 그래프를 끌고 들어와
+ * 순수 시험이 닿지 못한다(`tests/compiled.ts`). 대신 시험이 이 값과 `UserStatus.LOCKED` 가
+ * 같은지 확인하므로, 한쪽만 바뀌면 시험이 깨진다.
+ */
+export declare const LOCKED_STATUS = "locked";
+/**
+ * 잠금이 언제 풀리나. 잠금이 아니거나 자동해제가 없으면 `null`.
+ *
+ * `lockedAt` 이 없으면 계산할 수 없으므로 `null` 을 준다 — 그때 `isAccountLocked` 는
+ * **잠금을 유지한다**(아래 참조).
+ */
+export declare function accountLockExpiresAt(facts: AccountLockFacts, durationMinutes: number): Date | null;
+/**
+ * 잠금이 아직 유효한가.
+ *
+ * ## 한 칸이 두 물음에 답하지 않는다
+ *
+ * 섞이기 쉬운 두 사실이다.
+ *
+ * ```
+ * ① 이 계정이 잠겼나         ← `status` 가 답한다. 이 함수의 문이다
+ * ② 언제 자동으로 풀리나      ← `lockedAt` 이 답한다. 잠긴 것에 대해서만 묻는다
+ * ```
+ *
+ * 그래서 `status` 를 먼저 보고, 잠금이 아니면 **`lockedAt` 을 아예 보지 않는다.** 이 순서를
+ * 뒤집으면 사고가 양쪽으로 난다 — `lockedAt` 만 보고 판정하면 **한 번도 잠긴 적 없는 계정**
+ * (칸이 비어 있다)까지 잠김이 되어 배포하는 순간 전원이 못 들어오고, 반대로 짜면 지금 잠긴
+ * 계정이 전부 풀린다.
+ *
+ * `lockedAt` 이 비어 있다는 것은 「잠겼다」가 아니라 **「자동 해제가 없다」**는 뜻이다. 이 변경
+ * 전에 잠긴 행이 그렇고, 그 경우 관리자(`activateUser`)와 잠금 해제 메일이 푸는 길로 남는다 —
+ * 계산할 수 없는 것을 풀어 주는 쪽으로 기울면 잠긴 계정 전체가 조용히 열린다.
+ *
+ * @param now 판정 시각. 시험이 시계를 넘길 수 있게 인자로 받는다.
+ */
+export declare function isAccountLocked(facts: AccountLockFacts, now: Date, durationMinutes: number): boolean;
+/** 잠금이 시간이 지나 풀렸는가 — 행을 되돌려야 하는지 묻는 자리. */
+export declare function isAccountLockExpired(facts: AccountLockFacts, now: Date, durationMinutes: number): boolean;

package/dist-server/utils/account-lock-rule.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * 계정 잠금이 아직 유효한지를 판정하는 규칙 (순수 함수).
+ *
+ * ## 왜 따로 있나
+ *
+ * 잠금을 보는 자리가 둘이다 — `signin`(들어오려는 사람)과 `User.checkAuth`(요청마다 토큰을
+ * 확인하는 자리). 두 곳이 각자 「아직 잠겼나」를 판단하면 서로 다른 답을 낼 수 있고, 그러면
+ * 로그인은 되는데 요청은 거절되는(또는 그 반대) 상태가 생긴다. 판정은 한 곳에 둔다
+ * (`checkin-domain-rule` 과 같은 규율).
+ *
+ * ## 자동해제를 주기 작업으로 하지 않는 이유
+ *
+ * 계정이 10만이면 「만료된 잠금을 풀어 주는 일」이 따로 일이 된다. 잠금은 **읽는 시점에**
+ * 판정한다 — 그 계정을 보는 사람이 있을 때만 계산하면 되고, 그때가 유일하게 답이 필요한
+ * 순간이다.
+ *
+ * 행을 정리하는 것은 판정과 별개다. `signin` 은 판정이 「풀렸다」로 나오면 그 자리에서 행을
+ * 되돌리고(`ACTIVATED` · `failCount` 0 · `lockedAt` 비움) 계속 진행한다. `checkAuth` 는
+ * 매 요청 경로이므로 **읽기만 한다** — 판정만 보고 통과시키고, 행 정리는 다음 `signin` 이 한다.
+ *
+ * ## 잠금이 곧 셈의 창이다
+ *
+ * 자동해제 때 `failCount` 를 0 으로 두므로, 실패 셈은 「한 번의 잠금 안에서」만 쌓인다.
+ * 그래서 칸을 하나만 더해도 창이 생긴다.
+ *
+ * 남는 것: 잠기지 **않은** 동안의 셈은 여전히 누적이다(성공하면 0 으로 돌아간다). 그래서 오타를
+ * 드물게 다섯 번 내는 사람은 한 번 잠긴다 — 그 뒤 자동으로 풀리므로 견딜 수 있지만, 창을
+ * 정확히 하려면 「실패가 시작된 시각」 칸이 하나 더 필요하다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCKED_STATUS = exports.LOCK_FOREVER = void 0;
+exports.accountLockExpiresAt = accountLockExpiresAt;
+exports.isAccountLocked = isAccountLocked;
+exports.isAccountLockExpired = isAccountLockExpired;
+/** 잠금이 풀리지 않는 설정값 — 0 이하는 「자동해제 없음」이다. */
+exports.LOCK_FOREVER = 0;
+/**
+ * `UserStatus.LOCKED` 의 값.
+ *
+ * 엔티티를 import 하지 않는다 — 그러면 이 모듈이 type-graphql 데코레이터 그래프를 끌고 들어와
+ * 순수 시험이 닿지 못한다(`tests/compiled.ts`). 대신 시험이 이 값과 `UserStatus.LOCKED` 가
+ * 같은지 확인하므로, 한쪽만 바뀌면 시험이 깨진다.
+ */
+exports.LOCKED_STATUS = 'locked';
+/**
+ * 잠금이 언제 풀리나. 잠금이 아니거나 자동해제가 없으면 `null`.
+ *
+ * `lockedAt` 이 없으면 계산할 수 없으므로 `null` 을 준다 — 그때 `isAccountLocked` 는
+ * **잠금을 유지한다**(아래 참조).
+ */
+function accountLockExpiresAt(facts, durationMinutes) {
+    if (!isLockedStatus(facts)) {
+        return null;
+    }
+    if (!(durationMinutes > exports.LOCK_FOREVER)) {
+        return null;
+    }
+    const lockedAt = toDate(facts?.lockedAt);
+    if (!lockedAt) {
+        return null;
+    }
+    return new Date(lockedAt.getTime() + durationMinutes * 60 * 1000);
+}
+/**
+ * 잠금이 아직 유효한가.
+ *
+ * ## 한 칸이 두 물음에 답하지 않는다
+ *
+ * 섞이기 쉬운 두 사실이다.
+ *
+ * ```
+ * ① 이 계정이 잠겼나         ← `status` 가 답한다. 이 함수의 문이다
+ * ② 언제 자동으로 풀리나      ← `lockedAt` 이 답한다. 잠긴 것에 대해서만 묻는다
+ * ```
+ *
+ * 그래서 `status` 를 먼저 보고, 잠금이 아니면 **`lockedAt` 을 아예 보지 않는다.** 이 순서를
+ * 뒤집으면 사고가 양쪽으로 난다 — `lockedAt` 만 보고 판정하면 **한 번도 잠긴 적 없는 계정**
+ * (칸이 비어 있다)까지 잠김이 되어 배포하는 순간 전원이 못 들어오고, 반대로 짜면 지금 잠긴
+ * 계정이 전부 풀린다.
+ *
+ * `lockedAt` 이 비어 있다는 것은 「잠겼다」가 아니라 **「자동 해제가 없다」**는 뜻이다. 이 변경
+ * 전에 잠긴 행이 그렇고, 그 경우 관리자(`activateUser`)와 잠금 해제 메일이 푸는 길로 남는다 —
+ * 계산할 수 없는 것을 풀어 주는 쪽으로 기울면 잠긴 계정 전체가 조용히 열린다.
+ *
+ * @param now 판정 시각. 시험이 시계를 넘길 수 있게 인자로 받는다.
+ */
+function isAccountLocked(facts, now, durationMinutes) {
+    if (!isLockedStatus(facts)) {
+        return false;
+    }
+    const expiresAt = accountLockExpiresAt(facts, durationMinutes);
+    if (!expiresAt) {
+        /* 자동해제가 없거나(`durationMinutes <= 0`) 언제 풀릴지 모른다(`lockedAt` 없음). */
+        return true;
+    }
+    return now.getTime() < expiresAt.getTime();
+}
+/** 잠금이 시간이 지나 풀렸는가 — 행을 되돌려야 하는지 묻는 자리. */
+function isAccountLockExpired(facts, now, durationMinutes) {
+    return isLockedStatus(facts) && !isAccountLocked(facts, now, durationMinutes);
+}
+function isLockedStatus(facts) {
+    return facts?.status === exports.LOCKED_STATUS;
+}
+/** `Date` 로 오기도 하고 드라이버에 따라 문자열로 오기도 한다. */
+function toDate(value) {
+    if (!value) {
+        return null;
+    }
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+//# sourceMappingURL=account-lock-rule.js.map

package/dist-server/utils/account-lock-rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-lock-rule.js","sourceRoot":"","sources":["../../server/utils/account-lock-rule.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AA4BH,oDAeC;AAyBD,0CAYC;AAGD,oDAEC;AA3ED,0CAA0C;AAC7B,QAAA,YAAY,GAAG,CAAC,CAAA;AAE7B;;;;;;GAMG;AACU,QAAA,aAAa,GAAG,QAAQ,CAAA;AAErC;;;;;GAKG;AACH,SAAgB,oBAAoB,CAAC,KAAuB,EAAE,eAAuB;IACnF,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,CAAC,CAAC,eAAe,GAAG,oBAAY,CAAC,EAAE,CAAC;QACtC,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IACxC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,eAAe,GAAG,EAAE,GAAG,IAAI,CAAC,CAAA;AACnE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,eAAe,CAAC,KAAuB,EAAE,GAAS,EAAE,eAAuB;IACzF,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,SAAS,GAAG,oBAAoB,CAAC,KAAK,EAAE,eAAe,CAAC,CAAA;IAC9D,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,kEAAkE;QAClE,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,GAAG,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE,CAAA;AAC5C,CAAC;AAED,2CAA2C;AAC3C,SAAgB,oBAAoB,CAAC,KAAuB,EAAE,GAAS,EAAE,eAAuB;IAC9F,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,GAAG,EAAE,eAAe,CAAC,CAAA;AAC/E,CAAC;AAED,SAAS,cAAc,CAAC,KAAuB;IAC7C,OAAO,KAAK,EAAE,MAAM,KAAK,qBAAa,CAAA;AACxC,CAAC;AAED,4CAA4C;AAC5C,SAAS,MAAM,CAAC,KAAuC;IACrD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,YAAY,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAA;IAE5D,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA;AACnD,CAAC","sourcesContent":["/**\n * 계정 잠금이 아직 유효한지를 판정하는 규칙 (순수 함수).\n *\n * ## 왜 따로 있나\n *\n * 잠금을 보는 자리가 둘이다 — `signin`(들어오려는 사람)과 `User.checkAuth`(요청마다 토큰을\n * 확인하는 자리). 두 곳이 각자 「아직 잠겼나」를 판단하면 서로 다른 답을 낼 수 있고, 그러면\n * 로그인은 되는데 요청은 거절되는(또는 그 반대) 상태가 생긴다. 판정은 한 곳에 둔다\n * (`checkin-domain-rule` 과 같은 규율).\n *\n * ## 자동해제를 주기 작업으로 하지 않는 이유\n *\n * 계정이 10만이면 「만료된 잠금을 풀어 주는 일」이 따로 일이 된다. 잠금은 **읽는 시점에**\n * 판정한다 — 그 계정을 보는 사람이 있을 때만 계산하면 되고, 그때가 유일하게 답이 필요한\n * 순간이다.\n *\n * 행을 정리하는 것은 판정과 별개다. `signin` 은 판정이 「풀렸다」로 나오면 그 자리에서 행을\n * 되돌리고(`ACTIVATED` · `failCount` 0 · `lockedAt` 비움) 계속 진행한다. `checkAuth` 는\n * 매 요청 경로이므로 **읽기만 한다** — 판정만 보고 통과시키고, 행 정리는 다음 `signin` 이 한다.\n *\n * ## 잠금이 곧 셈의 창이다\n *\n * 자동해제 때 `failCount` 를 0 으로 두므로, 실패 셈은 「한 번의 잠금 안에서」만 쌓인다.\n * 그래서 칸을 하나만 더해도 창이 생긴다.\n *\n * 남는 것: 잠기지 **않은** 동안의 셈은 여전히 누적이다(성공하면 0 으로 돌아간다). 그래서 오타를\n * 드물게 다섯 번 내는 사람은 한 번 잠긴다 — 그 뒤 자동으로 풀리므로 견딜 수 있지만, 창을\n * 정확히 하려면 「실패가 시작된 시각」 칸이 하나 더 필요하다.\n */\n\n/** 판정에 필요한 사용자 측 사실들 — 조회는 부르는 쪽이 한다. */\nexport type AccountLockFacts = {\n  /** `UserStatus` 값. `'locked'` 가 아니면 잠금이 아니다. */\n  status?: string | null\n  /** 잠긴 시각. 이 변경 전에 잠긴 행에는 없다. */\n  lockedAt?: Date | string | null\n}\n\n/** 잠금이 풀리지 않는 설정값 — 0 이하는 「자동해제 없음」이다. */\nexport const LOCK_FOREVER = 0\n\n/**\n * `UserStatus.LOCKED` 의 값.\n *\n * 엔티티를 import 하지 않는다 — 그러면 이 모듈이 type-graphql 데코레이터 그래프를 끌고 들어와\n * 순수 시험이 닿지 못한다(`tests/compiled.ts`). 대신 시험이 이 값과 `UserStatus.LOCKED` 가\n * 같은지 확인하므로, 한쪽만 바뀌면 시험이 깨진다.\n */\nexport const LOCKED_STATUS = 'locked'\n\n/**\n * 잠금이 언제 풀리나. 잠금이 아니거나 자동해제가 없으면 `null`.\n *\n * `lockedAt` 이 없으면 계산할 수 없으므로 `null` 을 준다 — 그때 `isAccountLocked` 는\n * **잠금을 유지한다**(아래 참조).\n */\nexport function accountLockExpiresAt(facts: AccountLockFacts, durationMinutes: number): Date | null {\n  if (!isLockedStatus(facts)) {\n    return null\n  }\n\n  if (!(durationMinutes > LOCK_FOREVER)) {\n    return null\n  }\n\n  const lockedAt = toDate(facts?.lockedAt)\n  if (!lockedAt) {\n    return null\n  }\n\n  return new Date(lockedAt.getTime() + durationMinutes * 60 * 1000)\n}\n\n/**\n * 잠금이 아직 유효한가.\n *\n * ## 한 칸이 두 물음에 답하지 않는다\n *\n * 섞이기 쉬운 두 사실이다.\n *\n * ```\n * ① 이 계정이 잠겼나         ← `status` 가 답한다. 이 함수의 문이다\n * ② 언제 자동으로 풀리나      ← `lockedAt` 이 답한다. 잠긴 것에 대해서만 묻는다\n * ```\n *\n * 그래서 `status` 를 먼저 보고, 잠금이 아니면 **`lockedAt` 을 아예 보지 않는다.** 이 순서를\n * 뒤집으면 사고가 양쪽으로 난다 — `lockedAt` 만 보고 판정하면 **한 번도 잠긴 적 없는 계정**\n * (칸이 비어 있다)까지 잠김이 되어 배포하는 순간 전원이 못 들어오고, 반대로 짜면 지금 잠긴\n * 계정이 전부 풀린다.\n *\n * `lockedAt` 이 비어 있다는 것은 「잠겼다」가 아니라 **「자동 해제가 없다」**는 뜻이다. 이 변경\n * 전에 잠긴 행이 그렇고, 그 경우 관리자(`activateUser`)와 잠금 해제 메일이 푸는 길로 남는다 —\n * 계산할 수 없는 것을 풀어 주는 쪽으로 기울면 잠긴 계정 전체가 조용히 열린다.\n *\n * @param now 판정 시각. 시험이 시계를 넘길 수 있게 인자로 받는다.\n */\nexport function isAccountLocked(facts: AccountLockFacts, now: Date, durationMinutes: number): boolean {\n  if (!isLockedStatus(facts)) {\n    return false\n  }\n\n  const expiresAt = accountLockExpiresAt(facts, durationMinutes)\n  if (!expiresAt) {\n    /* 자동해제가 없거나(`durationMinutes <= 0`) 언제 풀릴지 모른다(`lockedAt` 없음). */\n    return true\n  }\n\n  return now.getTime() < expiresAt.getTime()\n}\n\n/** 잠금이 시간이 지나 풀렸는가 — 행을 되돌려야 하는지 묻는 자리. */\nexport function isAccountLockExpired(facts: AccountLockFacts, now: Date, durationMinutes: number): boolean {\n  return isLockedStatus(facts) && !isAccountLocked(facts, now, durationMinutes)\n}\n\nfunction isLockedStatus(facts: AccountLockFacts): boolean {\n  return facts?.status === LOCKED_STATUS\n}\n\n/** `Date` 로 오기도 하고 드라이버에 따라 문자열로 오기도 한다. */\nfunction toDate(value: Date | string | null | undefined): Date | null {\n  if (!value) {\n    return null\n  }\n\n  const date = value instanceof Date ? value : new Date(value)\n\n  return Number.isNaN(date.getTime()) ? null : date\n}\n"]}

package/dist-server/utils/lock-duration.d.ts

@@ -0,0 +1,3 @@
+import { LOCK_FOREVER } from './account-lock-rule.js';
+export declare function lockDurationMinutes(): number;
+export { LOCK_FOREVER };

package/dist-server/utils/lock-duration.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCK_FOREVER = void 0;
+exports.lockDurationMinutes = lockDurationMinutes;
+const env_1 = require("@things-factory/env");
+const account_lock_rule_js_1 = require("./account-lock-rule.js");
+Object.defineProperty(exports, "LOCK_FOREVER", { enumerable: true, get: function () { return account_lock_rule_js_1.LOCK_FOREVER; } });
+/**
+ * 잠금이 스스로 풀리기까지의 시간(분). **설정 이름이 있는 유일한 자리다.**
+ *
+ * 판정 규칙(`account-lock-rule.ts`)은 이 값을 인자로 받는다 — 설정을 읽지 않으므로 순수하게
+ * 남고, 시험이 시계와 기간을 둘 다 넘길 수 있다. 그 값을 어디서 가져오나는 이 파일이 안다.
+ *
+ * 잠금은 비밀번호 실패가 만드는 것이므로 기존 `password` 설정 블록 안에 둔다.
+ *
+ *   password:
+ *     lockDurationMinutes: 10      # 기본값. 0 이하면 자동해제 없음(관리자·메일로만 풀린다)
+ *
+ * ⚠ 이름은 아키텍트 확인 대기다 — 블록의 자리(`password`)는 확인받았고 칸 이름은 이것으로
+ *   진행했다. 바뀌면 이 파일 한 줄만 고친다.
+ */
+const DEFAULT_LOCK_DURATION_MINUTES = 10;
+function lockDurationMinutes() {
+    const configured = (env_1.config.get('password') || {}).lockDurationMinutes;
+    if (configured === undefined || configured === null) {
+        return DEFAULT_LOCK_DURATION_MINUTES;
+    }
+    const minutes = Number(configured);
+    /*
+     * 설정에 읽을 수 없는 값이 들어오면 **기본값으로 돌아간다.** `NaN` 을 그대로 흘리면
+     * 판정 규칙이 그것을 「자동해제 없음」으로 읽어(0 보다 크지 않으므로) 잠금이 영구가 된다 —
+     * 오타 하나가 조용히 정책을 바꾸는 자리가 된다.
+     */
+    return Number.isFinite(minutes) ? minutes : DEFAULT_LOCK_DURATION_MINUTES;
+}
+//# sourceMappingURL=lock-duration.js.map

package/dist-server/utils/lock-duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-duration.js","sourceRoot":"","sources":["../../server/utils/lock-duration.ts"],"names":[],"mappings":";;;AAoBA,kDAeC;AAnCD,6CAA4C;AAE5C,iEAAqD;AAmC5C,6FAnCA,mCAAY,OAmCA;AAjCrB;;;;;;;;;;;;;GAaG;AACH,MAAM,6BAA6B,GAAG,EAAE,CAAA;AAExC,SAAgB,mBAAmB;IACjC,MAAM,UAAU,GAAG,CAAC,YAAM,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,mBAAmB,CAAA;IAErE,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACpD,OAAO,6BAA6B,CAAA;IACtC,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,CAAA;IAElC;;;;OAIG;IACH,OAAO,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,6BAA6B,CAAA;AAC3E,CAAC","sourcesContent":["import { config } from '@things-factory/env'\n\nimport { LOCK_FOREVER } from './account-lock-rule.js'\n\n/**\n * 잠금이 스스로 풀리기까지의 시간(분). **설정 이름이 있는 유일한 자리다.**\n *\n * 판정 규칙(`account-lock-rule.ts`)은 이 값을 인자로 받는다 — 설정을 읽지 않으므로 순수하게\n * 남고, 시험이 시계와 기간을 둘 다 넘길 수 있다. 그 값을 어디서 가져오나는 이 파일이 안다.\n *\n * 잠금은 비밀번호 실패가 만드는 것이므로 기존 `password` 설정 블록 안에 둔다.\n *\n *   password:\n *     lockDurationMinutes: 10      # 기본값. 0 이하면 자동해제 없음(관리자·메일로만 풀린다)\n *\n * ⚠ 이름은 아키텍트 확인 대기다 — 블록의 자리(`password`)는 확인받았고 칸 이름은 이것으로\n *   진행했다. 바뀌면 이 파일 한 줄만 고친다.\n */\nconst DEFAULT_LOCK_DURATION_MINUTES = 10\n\nexport function lockDurationMinutes(): number {\n  const configured = (config.get('password') || {}).lockDurationMinutes\n\n  if (configured === undefined || configured === null) {\n    return DEFAULT_LOCK_DURATION_MINUTES\n  }\n\n  const minutes = Number(configured)\n\n  /*\n   * 설정에 읽을 수 없는 값이 들어오면 **기본값으로 돌아간다.** `NaN` 을 그대로 흘리면\n   * 판정 규칙이 그것을 「자동해제 없음」으로 읽어(0 보다 크지 않으므로) 잠금이 영구가 된다 —\n   * 오타 하나가 조용히 정책을 바꾸는 자리가 된다.\n   */\n  return Number.isFinite(minutes) ? minutes : DEFAULT_LOCK_DURATION_MINUTES\n}\n\nexport { LOCK_FOREVER }\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/auth-base",
-  "version": "10.1.3",
+  "version": "10.1.6",
   "main": "dist-server/index.js",
   "browser": "dist-client/index.js",
   "things-factory": true,
@@ -34,9 +34,9 @@
     "@reduxjs/toolkit": "^2.2.5",
     "@simplewebauthn/browser": "^13.0.0",
     "@simplewebauthn/server": "^13.0.0",
-    "@things-factory/email-base": "^10.1.3",
+    "@things-factory/email-base": "^10.1.4",
     "@things-factory/env": "^10.1.3",
-    "@things-factory/shell": "^10.1.3",
+    "@things-factory/shell": "^10.1.4",
     "@things-factory/utils": "^10.1.3",
     "@types/webappsec-credential-management": "^0.6.9",
     "jsonwebtoken": "^9.0.0",
@@ -48,5 +48,5 @@
     "passport-jwt": "^4.0.0",
     "passport-local": "^1.0.0"
   },
-  "gitHead": "406ecbf0d844099c41644531fe1a5ef5bddac84e"
+  "gitHead": "963aeb9ac470be5aea05bb5842a0a92afcab6036"
 }

package/tests/account-lock-db.test.ts

@@ -0,0 +1,216 @@
+/**
+ * 잠금이 스스로 풀리는 것 — 실 경로(`signin` · `checkAuth`)를 태워 본다.
+ *
+ * `account-lock-rule.test.ts` 는 규칙만 본다. 규칙이 옳아도 **부르는 자리**가 틀리면 계정은
+ * 영구히 잠긴 채로 남는다. 그래서 여기서는 실제 컨트롤러를 태우고 **행을 다시 읽는다.**
+ *
+ * 시계는 넘길 수 없으므로(컨트롤러가 안에서 `new Date()` 를 읽는다) **`lockedAt` 을 과거로
+ * 옮겨** 시간이 지난 상태를 만든다.
+ */
+
+import { config } from '@things-factory/env'
+
+import { closeAuthDatabase, Domain, getRepository, openAuthDatabase, resetAuthDatabase } from './db'
+import { loadCompiled } from './compiled'
+
+const { User } = loadCompiled('service/user/user')
+const { signin } = loadCompiled('controllers/signin')
+
+const PASSWORD = 'Passw0rd!'
+const WRONG = 'Wr0ngPass!'
+
+/** 기본값은 10분이다 — 설정이 없을 때의 값(`utils/lock-duration.ts`). */
+const DEFAULT_MINUTES = 10
+
+let domain: any
+
+async function seedUser(overrides: any = {}) {
+  const salt = User.generateSalt()
+
+  return await getRepository(User).save({
+    username: 'kim',
+    email: 'kim@example.com',
+    name: 'Kim',
+    salt,
+    password: User.encode(PASSWORD, salt),
+    status: 'activated',
+    domains: [domain],
+    ...overrides
+  })
+}
+
+const attempt = (password: string) => signin({ username: 'kim', password })
+
+const reload = (id: string) => getRepository(User).findOneBy({ id })
+
+/** 잠긴 시각을 `minutes` 분 전으로 옮긴다 — 시간이 지난 상태를 만드는 방법. */
+async function ageLock(id: string, minutes: number) {
+  await getRepository(User).update({ id }, { lockedAt: new Date(Date.now() - minutes * 60 * 1000) })
+}
+
+async function lockOut() {
+  const user = await seedUser()
+  for (let i = 0; i < 5; i++) {
+    await expect(attempt(WRONG)).rejects.toThrow()
+  }
+  return user
+}
+
+beforeAll(async () => {
+  await openAuthDatabase()
+})
+
+beforeEach(async () => {
+  await resetAuthDatabase()
+  domain = await getRepository(Domain).save({ name: 'plant-a', subdomain: 'plant-a' })
+})
+
+afterAll(async () => {
+  await closeAuthDatabase()
+})
+
+describe('잠글 때 시각을 남긴다', () => {
+  it('다섯 번째 실패에 `lockedAt` 이 써진다', async () => {
+    const before = Date.now()
+    const user = await lockOut()
+    const after = Date.now()
+
+    const locked = await reload(user.id)
+
+    expect(locked.status).toBe('locked')
+    expect(locked.lockedAt).toBeTruthy()
+
+    const at = new Date(locked.lockedAt).getTime()
+    expect(at).toBeGreaterThanOrEqual(before - 1000)
+    expect(at).toBeLessThanOrEqual(after + 1000)
+  })
+
+  it('네 번째까지는 시각이 없다', async () => {
+    const user = await seedUser()
+
+    for (let i = 0; i < 4; i++) {
+      await expect(attempt(WRONG)).rejects.toThrow()
+    }
+
+    const still = await reload(user.id)
+    expect(still.status).toBe('activated')
+    expect(still.lockedAt).toBeFalsy()
+  })
+})
+
+describe('기본 10분 안에는 잠겨 있다', () => {
+  it('맞는 비밀번호도 거절한다', async () => {
+    const user = await lockOut()
+    await ageLock(user.id, DEFAULT_MINUTES - 1)
+
+    await expect(attempt(PASSWORD)).rejects.toThrow()
+    expect((await reload(user.id)).status).toBe('locked')
+  })
+})
+
+describe('시간이 지나면 스스로 풀린다', () => {
+  it('맞는 비밀번호로 들어가진다', async () => {
+    const user = await lockOut()
+    await ageLock(user.id, DEFAULT_MINUTES + 1)
+
+    const result = await attempt(PASSWORD)
+
+    expect(result.token).toBeTruthy()
+  })
+
+  it('행이 되돌아간다 — 상태·셈·시각 셋 다', async () => {
+    const user = await lockOut()
+    await ageLock(user.id, DEFAULT_MINUTES + 1)
+
+    await attempt(PASSWORD)
+
+    const released = await reload(user.id)
+    expect(released.status).toBe('activated')
+    expect(released.failCount).toBe(0)
+    expect(released.lockedAt).toBeFalsy()
+  })
+
+  it('풀린 뒤 틀려도 셈이 1 부터 다시 센다 — 잠금이 곧 창이다', async () => {
+    const user = await lockOut()
+    await ageLock(user.id, DEFAULT_MINUTES + 1)
+
+    /* 틀린 비밀번호로도 잠금이 풀린다 — 판정이 대조보다 먼저다. */
+    await expect(attempt(WRONG)).rejects.toThrow()
+
+    const after = await reload(user.id)
+    expect(after.status).toBe('activated')
+    expect(after.failCount).toBe(1)
+    expect(after.lockedAt).toBeFalsy()
+  })
+
+  it('다시 잠기려면 다섯 번을 새로 틀려야 한다', async () => {
+    const user = await lockOut()
+    await ageLock(user.id, DEFAULT_MINUTES + 1)
+
+    for (let i = 0; i < 4; i++) {
+      await expect(attempt(WRONG)).rejects.toThrow()
+    }
+    expect((await reload(user.id)).status).toBe('activated')
+
+    await expect(attempt(WRONG)).rejects.toThrow()
+    expect((await reload(user.id)).status).toBe('locked')
+  })
+})
+
+describe('`lockedAt` 이 없는 잠긴 행 — 이 변경 전에 잠긴 것', () => {
+  it('풀리지 않는다', async () => {
+    /* 조용히 열리는 쪽으로 기울면 잠긴 계정 전체가 한 번에 열린다. 관리자(`activateUser`)와
+       잠금 해제 메일이 푸는 길로 남긴다. */
+    const user = await seedUser({ status: 'locked', failCount: 5, lockedAt: null })
+
+    await expect(attempt(PASSWORD)).rejects.toThrow()
+    expect((await reload(user.id)).status).toBe('locked')
+  })
+})
+
+describe('요청 경로(`checkAuth`)도 같은 판정을 쓴다', () => {
+  it('잠긴 동안에는 토큰을 거절한다', async () => {
+    const user = await lockOut()
+    await ageLock(user.id, DEFAULT_MINUTES - 1)
+
+    await expect(User.checkAuth({ username: 'kim' })).rejects.toThrow()
+  })
+
+  it('시간이 지나면 통과시킨다 — 그리고 **행을 고치지 않는다**', async () => {
+    /* 매 요청 지나는 경로라 쓰기를 얹지 않는다. 행 정리는 다음 `signin` 이 한다. */
+    const user = await lockOut()
+    await ageLock(user.id, DEFAULT_MINUTES + 1)
+
+    const authed = await User.checkAuth({ username: 'kim' })
+    expect(authed.id).toBe(user.id)
+
+    const untouched = await reload(user.id)
+    expect(untouched.status).toBe('locked')
+    expect(untouched.lockedAt).toBeTruthy()
+  })
+})
+
+describe('설정으로 자동해제를 끌 수 있다', () => {
+  afterEach(() => {
+    config.set('password', undefined)
+  })
+
+  it('0 이면 시간이 지나도 풀리지 않는다', async () => {
+    config.set('password', { lockDurationMinutes: 0 })
+
+    const user = await lockOut()
+    await ageLock(user.id, 60 * 24 * 365)
+
+    await expect(attempt(PASSWORD)).rejects.toThrow()
+    expect((await reload(user.id)).status).toBe('locked')
+  })
+
+  it('설정한 분이 지나면 풀린다', async () => {
+    config.set('password', { lockDurationMinutes: 1 })
+
+    const user = await lockOut()
+    await ageLock(user.id, 2)
+
+    expect((await attempt(PASSWORD)).token).toBeTruthy()
+  })
+})

package/tests/account-lock-rule.test.ts

@@ -0,0 +1,141 @@
+/**
+ * 계정 잠금 판정 규칙 시험 — 순수 함수라 엔티티에 닿지 않는다.
+ *
+ * 이 규칙이 하는 일은 하나다: 「이 잠금이 아직 유효한가」. 그 답을 두 곳이 쓴다 —
+ * `signin`(들어오려는 사람)과 `User.checkAuth`(요청마다). 두 곳이 각자 판단하면 로그인은
+ * 되는데 요청은 거절되는 상태가 생기므로 규칙을 한 곳에 두었고, 여기서 그 규칙만 본다.
+ *
+ * 시계를 인자로 받으므로 「10분 뒤」를 기다리지 않고 시험한다.
+ */
+
+import {
+  AccountLockFacts,
+  LOCKED_STATUS,
+  LOCK_FOREVER,
+  accountLockExpiresAt,
+  isAccountLocked,
+  isAccountLockExpired
+} from '../server/utils/account-lock-rule.js'
+import { loadCompiled } from './compiled'
+
+const MINUTES = 10
+const AT = new Date('2026-09-10T09:00:00.000Z')
+const minutesAfter = (n: number) => new Date(AT.getTime() + n * 60 * 1000)
+
+const locked = (overrides: Partial<AccountLockFacts> = {}): AccountLockFacts => ({
+  status: LOCKED_STATUS,
+  lockedAt: AT,
+  ...overrides
+})
+
+describe('엔티티와 값이 어긋나지 않는다', () => {
+  it('`LOCKED_STATUS` 가 `UserStatus.LOCKED` 와 같다', () => {
+    /* 이 규칙은 엔티티를 import 하지 않는다(그러면 순수 시험이 닿지 못한다). 그래서 두 값이
+       어긋나는 것을 막는 것은 이 시험뿐이다. */
+    const { UserStatus } = loadCompiled('service/user/user')
+
+    expect(LOCKED_STATUS).toBe(UserStatus.LOCKED)
+  })
+})
+
+describe('잠금이 아닌 상태', () => {
+  it('활성 계정은 잠금이 아니다', () => {
+    for (const status of ['activated', 'inactive', 'deleted', 'banned', 'password_reset_required']) {
+      expect(isAccountLocked({ status, lockedAt: AT }, AT, MINUTES)).toBe(false)
+      expect(isAccountLockExpired({ status, lockedAt: AT }, AT, MINUTES)).toBe(false)
+      expect(accountLockExpiresAt({ status, lockedAt: AT }, MINUTES)).toBeNull()
+    }
+  })
+
+  it('사실이 비어 있어도 던지지 않는다', () => {
+    for (const facts of [undefined, null, {}, { status: null }] as any[]) {
+      expect(isAccountLocked(facts, AT, MINUTES)).toBe(false)
+    }
+  })
+})
+
+describe('시간이 지나면 풀린다', () => {
+  it('설정한 시간 안에는 잠겨 있다', () => {
+    expect(isAccountLocked(locked(), AT, MINUTES)).toBe(true)
+    expect(isAccountLocked(locked(), minutesAfter(9), MINUTES)).toBe(true)
+  })
+
+  it('설정한 시간이 지나면 풀린다', () => {
+    expect(isAccountLocked(locked(), minutesAfter(10), MINUTES)).toBe(false)
+    expect(isAccountLocked(locked(), minutesAfter(60), MINUTES)).toBe(false)
+  })
+
+  it('경계는 만료 시각을 포함하지 않는다 — 정확히 10분이면 풀린 것이다', () => {
+    const facts = locked()
+
+    expect(isAccountLocked(facts, minutesAfter(10 - 1 / 60000), MINUTES)).toBe(true)
+    expect(isAccountLocked(facts, minutesAfter(10), MINUTES)).toBe(false)
+  })
+
+  it('풀린 것을 따로 물을 수 있다 — 행을 되돌려야 하는지 판단하는 자리', () => {
+    expect(isAccountLockExpired(locked(), minutesAfter(5), MINUTES)).toBe(false)
+    expect(isAccountLockExpired(locked(), minutesAfter(15), MINUTES)).toBe(true)
+  })
+
+  it('만료 시각을 계산해 준다', () => {
+    expect(accountLockExpiresAt(locked(), MINUTES)).toEqual(minutesAfter(10))
+  })
+
+  it('드라이버가 문자열로 준 시각도 읽는다', () => {
+    /* sqlite·mssql 은 `Date` 대신 문자열을 주기도 한다. */
+    const facts = locked({ lockedAt: AT.toISOString() })
+
+    expect(isAccountLocked(facts, minutesAfter(5), MINUTES)).toBe(true)
+    expect(isAccountLocked(facts, minutesAfter(15), MINUTES)).toBe(false)
+  })
+})
+
+describe('문은 `status` 가 지킨다 — `lockedAt` 이 아니다', () => {
+  it('한 번도 잠긴 적 없는 계정은 `lockedAt` 이 없어도 열려 있다', () => {
+    /*
+     * 이 한 줄이 배포 사고 하나를 막는다. 판정이 `lockedAt` 을 먼저 보면 칸이 비어 있는
+     * **모든** 계정(= 한 번도 잠긴 적 없는 계정 전부)이 잠김이 되어 아무도 못 들어온다.
+     * 그래서 `status` 를 먼저 보고, 잠금이 아니면 `lockedAt` 을 아예 보지 않는다.
+     */
+    const never = { status: 'activated' } as AccountLockFacts
+
+    expect(isAccountLocked(never, AT, MINUTES)).toBe(false)
+    expect(isAccountLockExpired(never, AT, MINUTES)).toBe(false)
+    expect(accountLockExpiresAt(never, MINUTES)).toBeNull()
+  })
+
+  it('자동해제를 끈 설정에서도 잠기지 않은 계정은 열려 있다', () => {
+    /* 「자동해제 없음」이 「전원 잠금」이 되지 않는다. */
+    expect(isAccountLocked({ status: 'activated' }, AT, LOCK_FOREVER)).toBe(false)
+    expect(isAccountLocked({ status: 'activated', lockedAt: null }, AT, LOCK_FOREVER)).toBe(false)
+  })
+})
+
+describe('잠긴 계정에서 `lockedAt` 이 없을 때', () => {
+  it('「잠겼다」가 아니라 **「자동 해제가 없다」**가 된다', () => {
+    /*
+     * 이 변경 전에 잠긴 행에는 칸이 비어 있다. 언제 풀릴지 계산할 수 없으니 자동으로는 안
+     * 풀린다 — 풀어 주는 쪽으로 기울면 **잠긴 계정 전체가 조용히 열린다.** 관리자
+     * (`activateUser`)와 잠금 해제 메일이 푸는 길로 남는다.
+     *
+     * 이것은 위 절과 짝이다: 잠금 여부는 `status` 가 정하고, 여기서 `lockedAt` 이 정하는 것은
+     * **해제 시각이 있나**뿐이다.
+     */
+    for (const lockedAt of [undefined, null, '', 'not-a-date'] as any[]) {
+      const facts = locked({ lockedAt })
+
+      expect(isAccountLocked(facts, minutesAfter(600), MINUTES)).toBe(true)
+      expect(isAccountLockExpired(facts, minutesAfter(600), MINUTES)).toBe(false)
+      expect(accountLockExpiresAt(facts, MINUTES)).toBeNull()
+    }
+  })
+})
+
+describe('자동해제를 끄는 설정', () => {
+  it('0 이하면 풀리지 않는다', () => {
+    for (const duration of [LOCK_FOREVER, 0, -1, undefined, null, NaN] as any[]) {
+      expect(isAccountLocked(locked(), minutesAfter(60 * 24 * 365), duration)).toBe(true)
+      expect(accountLockExpiresAt(locked(), duration)).toBeNull()
+    }
+  })
+})