@lacspace/lock 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lacspace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+<div align="center">
+
+# @lacspace/lock
+
+**Account lockout & brute-force protection — "server lock".**
+
+[![npm version](https://img.shields.io/npm/v/@lacspace/lock?color=%23a855f7&label=npm)](https://www.npmjs.com/package/@lacspace/lock)
+[![install size](https://packagephobia.com/badge?p=@lacspace/lock)](https://packagephobia.com/result?p=@lacspace/lock)
+[![minzipped](https://img.shields.io/bundlephobia/minzip/@lacspace/lock?label=minzip)](https://bundlephobia.com/package/@lacspace/lock)
+[![types](https://img.shields.io/badge/types-included-blue)](https://www.npmjs.com/package/@lacspace/lock)
+[![license](https://img.shields.io/npm/l/@lacspace/lock?color=green)](https://github.com/lacspace/npm-packages/blob/main/LICENSE)
+
+</div>
+
+> Stop credential-stuffing and brute force at the door. Track failed attempts per key (user, email, IP), lock after N strikes with **exponential backoff**, auto-expire the window, and reset on success. In-memory store built in; implement `LockStore` for Redis/Mongo.
+
+- 🔒 `record` / `check` / `reset` with a clear `LockStatus`
+- 📈 Exponential backoff up to a cap · self-resetting window
+- 🔌 Pluggable `LockStore` (memory included)
+- ⚡ Zero dependencies · 🌍 isomorphic · fully typed
+
+## Install
+
+```bash
+npm install @lacspace/lock
+```
+
+## Usage
+
+```ts
+import { lockout } from "@lacspace/lock";
+
+const guard = lockout({ maxAttempts: 5, baseDelayMs: 60_000, maxDelayMs: 3_600_000 });
+
+// before checking the password
+const status = await guard.check(email);
+if (status.locked) throw new Error(`Too many attempts. Try again in ${Math.ceil(status.retryAfterMs / 1000)}s`);
+
+if (await verifyPassword(input, stored)) {
+  await guard.reset(email);          // success — clear strikes
+} else {
+  const s = await guard.record(email); // failure — may lock
+  throw new Error(s.locked ? "Account temporarily locked." : `${s.remaining} attempts left`);
+}
+```
+
+## API
+
+| Export | Description |
+| --- | --- |
+| `lockout(opts?)` | `maxAttempts`, `baseDelayMs`, `maxDelayMs`, `windowMs`, `store` |
+| `.check(key)` | status without recording |
+| `.record(key)` | record a failure → new status |
+| `.reset(key)` | clear on success |
+| `MemoryLockStore` / `LockStore` | storage (bring your own for Redis) |
+
+`LockStatus` → `{ locked, attempts, remaining, retryAfterMs }`.
+
+## The Lacspace Security Kit
+
+| Package | For |
+| --- | --- |
+| [`@lacspace/crypto`](https://www.npmjs.com/package/@lacspace/crypto) | AES encryption & hashing |
+| [`@lacspace/password`](https://www.npmjs.com/package/@lacspace/password) | Password hashing |
+| [`@lacspace/jwt`](https://www.npmjs.com/package/@lacspace/jwt) | JWTs & tokens |
+| [`@lacspace/apikey`](https://www.npmjs.com/package/@lacspace/apikey) | API keys |
+| [`@lacspace/otp`](https://www.npmjs.com/package/@lacspace/otp) | TOTP/HOTP 2FA |
+| [`@lacspace/webauthn`](https://www.npmjs.com/package/@lacspace/webauthn) | Passkeys / biometric |
+| [`@lacspace/mfa`](https://www.npmjs.com/package/@lacspace/mfa) | 2FA/3FA orchestration |
+| **`@lacspace/lock`** | Account lockout (this package) |
+| [`@lacspace/headers`](https://www.npmjs.com/package/@lacspace/headers) | Secure headers / CSP |
+| [`@lacspace/redact`](https://www.npmjs.com/package/@lacspace/redact) | Log redaction |
+
+<div align="center"><sub>Built with care by <a href="https://lacspace.com">Lacspace</a> · MIT licensed · <a href="https://github.com/lacspace/npm-packages">source</a></sub></div>

package/dist/index.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+// src/index.ts
+var MemoryLockStore = class {
+  constructor() {
+    this.map = /* @__PURE__ */ new Map();
+  }
+  async get(key) {
+    return this.map.get(key);
+  }
+  async set(key, state) {
+    this.map.set(key, state);
+  }
+  async delete(key) {
+    this.map.delete(key);
+  }
+};
+var Lockout = class {
+  constructor(opts = {}) {
+    this.store = opts.store ?? new MemoryLockStore();
+    this.maxAttempts = opts.maxAttempts ?? 5;
+    this.baseDelayMs = opts.baseDelayMs ?? 6e4;
+    this.maxDelayMs = opts.maxDelayMs ?? 36e5;
+    this.windowMs = opts.windowMs ?? 9e5;
+  }
+  lockDuration(attempts) {
+    const over = attempts - this.maxAttempts;
+    if (over < 1) return 0;
+    return Math.min(this.maxDelayMs, this.baseDelayMs * 2 ** (over - 1));
+  }
+  status(state, now) {
+    if (!state) return { locked: false, attempts: 0, remaining: this.maxAttempts, retryAfterMs: 0 };
+    const locked = state.lockedUntil > now;
+    return {
+      locked,
+      attempts: state.attempts,
+      remaining: locked ? 0 : Math.max(0, this.maxAttempts - state.attempts),
+      retryAfterMs: locked ? state.lockedUntil - now : 0
+    };
+  }
+  /** Current lock status without recording an attempt. */
+  async check(key) {
+    const now = Date.now();
+    let state = await this.store.get(key);
+    if (state && now - state.firstAttempt > this.windowMs && state.lockedUntil <= now) {
+      await this.store.delete(key);
+      state = void 0;
+    }
+    return this.status(state, now);
+  }
+  /** Record a failed attempt and return the new status. */
+  async record(key) {
+    const now = Date.now();
+    let state = await this.store.get(key);
+    if (!state || now - state.firstAttempt > this.windowMs && state.lockedUntil <= now) {
+      state = { attempts: 0, lockedUntil: 0, firstAttempt: now };
+    }
+    state.attempts += 1;
+    const dur = this.lockDuration(state.attempts);
+    if (dur > 0) state.lockedUntil = now + dur;
+    await this.store.set(key, state);
+    return this.status(state, now);
+  }
+  /** Clear all state for a key (call on successful auth). */
+  async reset(key) {
+    await this.store.delete(key);
+  }
+};
+function lockout(opts) {
+  return new Lockout(opts);
+}
+
+exports.Lockout = Lockout;
+exports.MemoryLockStore = MemoryLockStore;
+exports.lockout = lockout;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AAyBO,IAAM,kBAAN,MAA2C;AAAA,EAA3C,WAAA,GAAA;AACL,IAAA,IAAA,CAAQ,GAAA,uBAAU,GAAA,EAA0B;AAAA,EAAA;AAAA,EAC5C,MAAM,IAAI,GAAA,EAAa;AACrB,IAAA,OAAO,IAAA,CAAK,GAAA,CAAI,GAAA,CAAI,GAAG,CAAA;AAAA,EACzB;AAAA,EACA,MAAM,GAAA,CAAI,GAAA,EAAa,KAAA,EAAqB;AAC1C,IAAA,IAAA,CAAK,GAAA,CAAI,GAAA,CAAI,GAAA,EAAK,KAAK,CAAA;AAAA,EACzB;AAAA,EACA,MAAM,OAAO,GAAA,EAAa;AACxB,IAAA,IAAA,CAAK,GAAA,CAAI,OAAO,GAAG,CAAA;AAAA,EACrB;AACF;AAuBO,IAAM,UAAN,MAAc;AAAA,EAOnB,WAAA,CAAY,IAAA,GAAuB,EAAC,EAAG;AACrC,IAAA,IAAA,CAAK,KAAA,GAAQ,IAAA,CAAK,KAAA,IAAS,IAAI,eAAA,EAAgB;AAC/C,IAAA,IAAA,CAAK,WAAA,GAAc,KAAK,WAAA,IAAe,CAAA;AACvC,IAAA,IAAA,CAAK,WAAA,GAAc,KAAK,WAAA,IAAe,GAAA;AACvC,IAAA,IAAA,CAAK,UAAA,GAAa,KAAK,UAAA,IAAc,IAAA;AACrC,IAAA,IAAA,CAAK,QAAA,GAAW,KAAK,QAAA,IAAY,GAAA;AAAA,EACnC;AAAA,EAEQ,aAAa,QAAA,EAA0B;AAE7C,IAAA,MAAM,IAAA,GAAO,WAAW,IAAA,CAAK,WAAA;AAC7B,IAAA,IAAI,IAAA,GAAO,GAAG,OAAO,CAAA;AACrB,IAAA,OAAO,IAAA,CAAK,IAAI,IAAA,CAAK,UAAA,EAAY,KAAK,WAAA,GAAc,CAAA,KAAM,OAAO,CAAA,CAAE,CAAA;AAAA,EACrE;AAAA,EAEQ,MAAA,CAAO,OAAiC,GAAA,EAAyB;AACvE,IAAA,IAAI,CAAC,KAAA,EAAO,OAAO,EAAE,MAAA,EAAQ,KAAA,EAAO,QAAA,EAAU,CAAA,EAAG,SAAA,EAAW,IAAA,CAAK,WAAA,EAAa,YAAA,EAAc,CAAA,EAAE;AAC9F,IAAA,MAAM,MAAA,GAAS,MAAM,WAAA,GAAc,GAAA;AACnC,IAAA,OAAO;AAAA,MACL,MAAA;AAAA,MACA,UAAU,KAAA,CAAM,QAAA;AAAA,MAChB,SAAA,EAAW,SAAS,CAAA,GAAI,IAAA,CAAK,IAAI,CAAA,EAAG,IAAA,CAAK,WAAA,GAAc,KAAA,CAAM,QAAQ,CAAA;AAAA,MACrE,YAAA,EAAc,MAAA,GAAS,KAAA,CAAM,WAAA,GAAc,GAAA,GAAM;AAAA,KACnD;AAAA,EACF;AAAA;AAAA,EAGA,MAAM,MAAM,GAAA,EAAkC;AAC5C,IAAA,MAAM,GAAA,GAAM,KAAK,GAAA,EAAI;AACrB,IAAA,IAAI,KAAA,GAAQ,MAAM,IAAA,CAAK,KAAA,CAAM,IAAI,GAAG,CAAA;AACpC,IAAA,IAAI,KAAA,IAAS,MAAM,KAAA,CAAM,YAAA,GAAe,KAAK,QAAA,IAAY,KAAA,CAAM,eAAe,GAAA,EAAK;AACjF,MAAA,MAAM,IAAA,CAAK,KAAA,CAAM,MAAA,CAAO,GAAG,CAAA;AAC3B,MAAA,KAAA,GAAQ,MAAA;AAAA,IACV;AACA,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,KAAA,EAAO,GAAG,CAAA;AAAA,EAC/B;AAAA;AAAA,EAGA,MAAM,OAAO,GAAA,EAAkC;AAC7C,IAAA,MAAM,GAAA,GAAM,KAAK,GAAA,EAAI;AACrB,IAAA,IAAI,KAAA,GAAQ,MAAM,IAAA,CAAK,KAAA,CAAM,IAAI,GAAG,CAAA;AACpC,IAAA,IAAI,CAAC,SAAU,GAAA,GAAM,KAAA,CAAM,eAAe,IAAA,CAAK,QAAA,IAAY,KAAA,CAAM,WAAA,IAAe,GAAA,EAAM;AACpF,MAAA,KAAA,GAAQ,EAAE,QAAA,EAAU,CAAA,EAAG,WAAA,EAAa,CAAA,EAAG,cAAc,GAAA,EAAI;AAAA,IAC3D;AACA,IAAA,KAAA,CAAM,QAAA,IAAY,CAAA;AAClB,IAAA,MAAM,GAAA,GAAM,IAAA,CAAK,YAAA,CAAa,KAAA,CAAM,QAAQ,CAAA;AAC5C,IAAA,IAAI,GAAA,GAAM,CAAA,EAAG,KAAA,CAAM,WAAA,GAAc,GAAA,GAAM,GAAA;AACvC,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,GAAA,EAAK,KAAK,CAAA;AAC/B,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,KAAA,EAAO,GAAG,CAAA;AAAA,EAC/B;AAAA;AAAA,EAGA,MAAM,MAAM,GAAA,EAA4B;AACtC,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,MAAA,CAAO,GAAG,CAAA;AAAA,EAC7B;AACF;AAEO,SAAS,QAAQ,IAAA,EAAgC;AACtD,EAAA,OAAO,IAAI,QAAQ,IAAI,CAAA;AACzB","file":"index.cjs","sourcesContent":["/**\n * @lacspace/lock\n * Account lockout & brute-force protection (\"server lock\").\n *\n * Track failed attempts per key (user, IP, email), lock after N strikes with\n * exponential backoff, and reset on success. Pluggable store (in-memory built\n * in; implement `LockStore` for Redis/Mongo).\n *\n * Zero dependencies · isomorphic · fully typed.\n */\n\nexport interface AttemptState {\n  attempts: number;\n  /** Epoch ms the key is locked until (0 = not locked). */\n  lockedUntil: number;\n  /** Epoch ms of the first attempt in the current window. */\n  firstAttempt: number;\n}\n\nexport interface LockStore {\n  get(key: string): Promise<AttemptState | undefined>;\n  set(key: string, state: AttemptState): Promise<void>;\n  delete(key: string): Promise<void>;\n}\n\nexport class MemoryLockStore implements LockStore {\n  private map = new Map<string, AttemptState>();\n  async get(key: string) {\n    return this.map.get(key);\n  }\n  async set(key: string, state: AttemptState) {\n    this.map.set(key, state);\n  }\n  async delete(key: string) {\n    this.map.delete(key);\n  }\n}\n\nexport interface LockoutOptions {\n  /** Failed attempts allowed before locking. Default 5. */\n  maxAttempts?: number;\n  /** Base lock duration in ms once the threshold is crossed. Default 60000 (1 min). */\n  baseDelayMs?: number;\n  /** Maximum lock duration in ms. Default 3600000 (1 hour). */\n  maxDelayMs?: number;\n  /** Window in ms after which the attempt counter resets on its own. Default 900000 (15 min). */\n  windowMs?: number;\n  store?: LockStore;\n}\n\nexport interface LockStatus {\n  locked: boolean;\n  attempts: number;\n  /** Attempts left before the next lock (0 when locked). */\n  remaining: number;\n  /** ms until unlock (0 when not locked). */\n  retryAfterMs: number;\n}\n\nexport class Lockout {\n  private store: LockStore;\n  private maxAttempts: number;\n  private baseDelayMs: number;\n  private maxDelayMs: number;\n  private windowMs: number;\n\n  constructor(opts: LockoutOptions = {}) {\n    this.store = opts.store ?? new MemoryLockStore();\n    this.maxAttempts = opts.maxAttempts ?? 5;\n    this.baseDelayMs = opts.baseDelayMs ?? 60000;\n    this.maxDelayMs = opts.maxDelayMs ?? 3600000;\n    this.windowMs = opts.windowMs ?? 900000;\n  }\n\n  private lockDuration(attempts: number): number {\n    // maxAttempts failures are allowed; locking begins once they're exceeded.\n    const over = attempts - this.maxAttempts;\n    if (over < 1) return 0;\n    return Math.min(this.maxDelayMs, this.baseDelayMs * 2 ** (over - 1));\n  }\n\n  private status(state: AttemptState | undefined, now: number): LockStatus {\n    if (!state) return { locked: false, attempts: 0, remaining: this.maxAttempts, retryAfterMs: 0 };\n    const locked = state.lockedUntil > now;\n    return {\n      locked,\n      attempts: state.attempts,\n      remaining: locked ? 0 : Math.max(0, this.maxAttempts - state.attempts),\n      retryAfterMs: locked ? state.lockedUntil - now : 0,\n    };\n  }\n\n  /** Current lock status without recording an attempt. */\n  async check(key: string): Promise<LockStatus> {\n    const now = Date.now();\n    let state = await this.store.get(key);\n    if (state && now - state.firstAttempt > this.windowMs && state.lockedUntil <= now) {\n      await this.store.delete(key);\n      state = undefined;\n    }\n    return this.status(state, now);\n  }\n\n  /** Record a failed attempt and return the new status. */\n  async record(key: string): Promise<LockStatus> {\n    const now = Date.now();\n    let state = await this.store.get(key);\n    if (!state || (now - state.firstAttempt > this.windowMs && state.lockedUntil <= now)) {\n      state = { attempts: 0, lockedUntil: 0, firstAttempt: now };\n    }\n    state.attempts += 1;\n    const dur = this.lockDuration(state.attempts);\n    if (dur > 0) state.lockedUntil = now + dur;\n    await this.store.set(key, state);\n    return this.status(state, now);\n  }\n\n  /** Clear all state for a key (call on successful auth). */\n  async reset(key: string): Promise<void> {\n    await this.store.delete(key);\n  }\n}\n\nexport function lockout(opts?: LockoutOptions): Lockout {\n  return new Lockout(opts);\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,66 @@
+/**
+ * @lacspace/lock
+ * Account lockout & brute-force protection ("server lock").
+ *
+ * Track failed attempts per key (user, IP, email), lock after N strikes with
+ * exponential backoff, and reset on success. Pluggable store (in-memory built
+ * in; implement `LockStore` for Redis/Mongo).
+ *
+ * Zero dependencies · isomorphic · fully typed.
+ */
+interface AttemptState {
+    attempts: number;
+    /** Epoch ms the key is locked until (0 = not locked). */
+    lockedUntil: number;
+    /** Epoch ms of the first attempt in the current window. */
+    firstAttempt: number;
+}
+interface LockStore {
+    get(key: string): Promise<AttemptState | undefined>;
+    set(key: string, state: AttemptState): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+declare class MemoryLockStore implements LockStore {
+    private map;
+    get(key: string): Promise<AttemptState | undefined>;
+    set(key: string, state: AttemptState): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+interface LockoutOptions {
+    /** Failed attempts allowed before locking. Default 5. */
+    maxAttempts?: number;
+    /** Base lock duration in ms once the threshold is crossed. Default 60000 (1 min). */
+    baseDelayMs?: number;
+    /** Maximum lock duration in ms. Default 3600000 (1 hour). */
+    maxDelayMs?: number;
+    /** Window in ms after which the attempt counter resets on its own. Default 900000 (15 min). */
+    windowMs?: number;
+    store?: LockStore;
+}
+interface LockStatus {
+    locked: boolean;
+    attempts: number;
+    /** Attempts left before the next lock (0 when locked). */
+    remaining: number;
+    /** ms until unlock (0 when not locked). */
+    retryAfterMs: number;
+}
+declare class Lockout {
+    private store;
+    private maxAttempts;
+    private baseDelayMs;
+    private maxDelayMs;
+    private windowMs;
+    constructor(opts?: LockoutOptions);
+    private lockDuration;
+    private status;
+    /** Current lock status without recording an attempt. */
+    check(key: string): Promise<LockStatus>;
+    /** Record a failed attempt and return the new status. */
+    record(key: string): Promise<LockStatus>;
+    /** Clear all state for a key (call on successful auth). */
+    reset(key: string): Promise<void>;
+}
+declare function lockout(opts?: LockoutOptions): Lockout;
+
+export { type AttemptState, type LockStatus, type LockStore, Lockout, type LockoutOptions, MemoryLockStore, lockout };

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @lacspace/lock
+ * Account lockout & brute-force protection ("server lock").
+ *
+ * Track failed attempts per key (user, IP, email), lock after N strikes with
+ * exponential backoff, and reset on success. Pluggable store (in-memory built
+ * in; implement `LockStore` for Redis/Mongo).
+ *
+ * Zero dependencies · isomorphic · fully typed.
+ */
+interface AttemptState {
+    attempts: number;
+    /** Epoch ms the key is locked until (0 = not locked). */
+    lockedUntil: number;
+    /** Epoch ms of the first attempt in the current window. */
+    firstAttempt: number;
+}
+interface LockStore {
+    get(key: string): Promise<AttemptState | undefined>;
+    set(key: string, state: AttemptState): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+declare class MemoryLockStore implements LockStore {
+    private map;
+    get(key: string): Promise<AttemptState | undefined>;
+    set(key: string, state: AttemptState): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+interface LockoutOptions {
+    /** Failed attempts allowed before locking. Default 5. */
+    maxAttempts?: number;
+    /** Base lock duration in ms once the threshold is crossed. Default 60000 (1 min). */
+    baseDelayMs?: number;
+    /** Maximum lock duration in ms. Default 3600000 (1 hour). */
+    maxDelayMs?: number;
+    /** Window in ms after which the attempt counter resets on its own. Default 900000 (15 min). */
+    windowMs?: number;
+    store?: LockStore;
+}
+interface LockStatus {
+    locked: boolean;
+    attempts: number;
+    /** Attempts left before the next lock (0 when locked). */
+    remaining: number;
+    /** ms until unlock (0 when not locked). */
+    retryAfterMs: number;
+}
+declare class Lockout {
+    private store;
+    private maxAttempts;
+    private baseDelayMs;
+    private maxDelayMs;
+    private windowMs;
+    constructor(opts?: LockoutOptions);
+    private lockDuration;
+    private status;
+    /** Current lock status without recording an attempt. */
+    check(key: string): Promise<LockStatus>;
+    /** Record a failed attempt and return the new status. */
+    record(key: string): Promise<LockStatus>;
+    /** Clear all state for a key (call on successful auth). */
+    reset(key: string): Promise<void>;
+}
+declare function lockout(opts?: LockoutOptions): Lockout;
+
+export { type AttemptState, type LockStatus, type LockStore, Lockout, type LockoutOptions, MemoryLockStore, lockout };

package/dist/index.js

@@ -0,0 +1,73 @@
+// src/index.ts
+var MemoryLockStore = class {
+  constructor() {
+    this.map = /* @__PURE__ */ new Map();
+  }
+  async get(key) {
+    return this.map.get(key);
+  }
+  async set(key, state) {
+    this.map.set(key, state);
+  }
+  async delete(key) {
+    this.map.delete(key);
+  }
+};
+var Lockout = class {
+  constructor(opts = {}) {
+    this.store = opts.store ?? new MemoryLockStore();
+    this.maxAttempts = opts.maxAttempts ?? 5;
+    this.baseDelayMs = opts.baseDelayMs ?? 6e4;
+    this.maxDelayMs = opts.maxDelayMs ?? 36e5;
+    this.windowMs = opts.windowMs ?? 9e5;
+  }
+  lockDuration(attempts) {
+    const over = attempts - this.maxAttempts;
+    if (over < 1) return 0;
+    return Math.min(this.maxDelayMs, this.baseDelayMs * 2 ** (over - 1));
+  }
+  status(state, now) {
+    if (!state) return { locked: false, attempts: 0, remaining: this.maxAttempts, retryAfterMs: 0 };
+    const locked = state.lockedUntil > now;
+    return {
+      locked,
+      attempts: state.attempts,
+      remaining: locked ? 0 : Math.max(0, this.maxAttempts - state.attempts),
+      retryAfterMs: locked ? state.lockedUntil - now : 0
+    };
+  }
+  /** Current lock status without recording an attempt. */
+  async check(key) {
+    const now = Date.now();
+    let state = await this.store.get(key);
+    if (state && now - state.firstAttempt > this.windowMs && state.lockedUntil <= now) {
+      await this.store.delete(key);
+      state = void 0;
+    }
+    return this.status(state, now);
+  }
+  /** Record a failed attempt and return the new status. */
+  async record(key) {
+    const now = Date.now();
+    let state = await this.store.get(key);
+    if (!state || now - state.firstAttempt > this.windowMs && state.lockedUntil <= now) {
+      state = { attempts: 0, lockedUntil: 0, firstAttempt: now };
+    }
+    state.attempts += 1;
+    const dur = this.lockDuration(state.attempts);
+    if (dur > 0) state.lockedUntil = now + dur;
+    await this.store.set(key, state);
+    return this.status(state, now);
+  }
+  /** Clear all state for a key (call on successful auth). */
+  async reset(key) {
+    await this.store.delete(key);
+  }
+};
+function lockout(opts) {
+  return new Lockout(opts);
+}
+
+export { Lockout, MemoryLockStore, lockout };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @lacspace/lock\n * Account lockout & brute-force protection (\"server lock\").\n *\n * Track failed attempts per key (user, IP, email), lock after N strikes with\n * exponential backoff, and reset on success. Pluggable store (in-memory built\n * in; implement `LockStore` for Redis/Mongo).\n *\n * Zero dependencies · isomorphic · fully typed.\n */\n\nexport interface AttemptState {\n  attempts: number;\n  /** Epoch ms the key is locked until (0 = not locked). */\n  lockedUntil: number;\n  /** Epoch ms of the first attempt in the current window. */\n  firstAttempt: number;\n}\n\nexport interface LockStore {\n  get(key: string): Promise<AttemptState | undefined>;\n  set(key: string, state: AttemptState): Promise<void>;\n  delete(key: string): Promise<void>;\n}\n\nexport class MemoryLockStore implements LockStore {\n  private map = new Map<string, AttemptState>();\n  async get(key: string) {\n    return this.map.get(key);\n  }\n  async set(key: string, state: AttemptState) {\n    this.map.set(key, state);\n  }\n  async delete(key: string) {\n    this.map.delete(key);\n  }\n}\n\nexport interface LockoutOptions {\n  /** Failed attempts allowed before locking. Default 5. */\n  maxAttempts?: number;\n  /** Base lock duration in ms once the threshold is crossed. Default 60000 (1 min). */\n  baseDelayMs?: number;\n  /** Maximum lock duration in ms. Default 3600000 (1 hour). */\n  maxDelayMs?: number;\n  /** Window in ms after which the attempt counter resets on its own. Default 900000 (15 min). */\n  windowMs?: number;\n  store?: LockStore;\n}\n\nexport interface LockStatus {\n  locked: boolean;\n  attempts: number;\n  /** Attempts left before the next lock (0 when locked). */\n  remaining: number;\n  /** ms until unlock (0 when not locked). */\n  retryAfterMs: number;\n}\n\nexport class Lockout {\n  private store: LockStore;\n  private maxAttempts: number;\n  private baseDelayMs: number;\n  private maxDelayMs: number;\n  private windowMs: number;\n\n  constructor(opts: LockoutOptions = {}) {\n    this.store = opts.store ?? new MemoryLockStore();\n    this.maxAttempts = opts.maxAttempts ?? 5;\n    this.baseDelayMs = opts.baseDelayMs ?? 60000;\n    this.maxDelayMs = opts.maxDelayMs ?? 3600000;\n    this.windowMs = opts.windowMs ?? 900000;\n  }\n\n  private lockDuration(attempts: number): number {\n    // maxAttempts failures are allowed; locking begins once they're exceeded.\n    const over = attempts - this.maxAttempts;\n    if (over < 1) return 0;\n    return Math.min(this.maxDelayMs, this.baseDelayMs * 2 ** (over - 1));\n  }\n\n  private status(state: AttemptState | undefined, now: number): LockStatus {\n    if (!state) return { locked: false, attempts: 0, remaining: this.maxAttempts, retryAfterMs: 0 };\n    const locked = state.lockedUntil > now;\n    return {\n      locked,\n      attempts: state.attempts,\n      remaining: locked ? 0 : Math.max(0, this.maxAttempts - state.attempts),\n      retryAfterMs: locked ? state.lockedUntil - now : 0,\n    };\n  }\n\n  /** Current lock status without recording an attempt. */\n  async check(key: string): Promise<LockStatus> {\n    const now = Date.now();\n    let state = await this.store.get(key);\n    if (state && now - state.firstAttempt > this.windowMs && state.lockedUntil <= now) {\n      await this.store.delete(key);\n      state = undefined;\n    }\n    return this.status(state, now);\n  }\n\n  /** Record a failed attempt and return the new status. */\n  async record(key: string): Promise<LockStatus> {\n    const now = Date.now();\n    let state = await this.store.get(key);\n    if (!state || (now - state.firstAttempt > this.windowMs && state.lockedUntil <= now)) {\n      state = { attempts: 0, lockedUntil: 0, firstAttempt: now };\n    }\n    state.attempts += 1;\n    const dur = this.lockDuration(state.attempts);\n    if (dur > 0) state.lockedUntil = now + dur;\n    await this.store.set(key, state);\n    return this.status(state, now);\n  }\n\n  /** Clear all state for a key (call on successful auth). */\n  async reset(key: string): Promise<void> {\n    await this.store.delete(key);\n  }\n}\n\nexport function lockout(opts?: LockoutOptions): Lockout {\n  return new Lockout(opts);\n}\n"]}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@lacspace/lock",
+  "version": "1.0.0",
+  "description": "Account lockout & brute-force protection (server lock) — N-strikes, exponential backoff, self-resetting window, pluggable store. Zero-dependency, isomorphic.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" }, "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" } } },
+  "files": ["dist"],
+  "sideEffects": false,
+  "scripts": { "build": "tsup", "prepublishOnly": "npm run build" },
+  "keywords": ["account-lockout", "brute-force", "login-security", "lockout", "backoff", "auth", "security", "typescript"],
+  "author": "Lacspace <contact@lacspace.com>",
+  "license": "MIT",
+  "homepage": "https://lacspace.com/packages",
+  "repository": { "type": "git", "url": "git+https://github.com/lacspace/npm-packages.git", "directory": "lock" },
+  "bugs": { "url": "https://github.com/lacspace/npm-packages/issues" },
+  "engines": { "node": ">=18" }
+}