@tryghost/brute-knex 3.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2014, llambda <xxgsoftware@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+~    

package/README.md

@@ -0,0 +1,104 @@
+# @tryghost/brute-knex
+
+Knex-backed store for [express-brute](https://github.com/AdamPflug/express-brute) that persists rate-limit state in SQL databases.
+
+[![NPM Version][npm-version-image]][npm-url]
+[![NPM Downloads][npm-downloads-image]][npm-url]
+[![Node.js Version][node-image]][node-url]
+[![NPM][npm-image]][npm-url]
+
+## What It Does
+
+`@tryghost/brute-knex` lets `express-brute` share brute-force counters through a Knex table instead of keeping them in process memory. It can create its storage table automatically, use a caller-provided Knex instance, or fall back to a local SQLite database when no Knex instance is supplied.
+
+The package supports Node.js `>=20.20.0`. CI exercises the store against SQLite, MySQL, and Postgres, with additional MySQL coverage for existing consumers that provide Knex `0.21.6`.
+
+## Installation
+
+Install the package and the Knex database driver your app uses:
+
+```sh
+npm install @tryghost/brute-knex knex mysql2
+```
+
+Use `pg` instead of `mysql2` for Postgres, or `sqlite3` for SQLite.
+
+## Usage
+
+```js
+const ExpressBrute = require('express-brute');
+const Knex = require('knex');
+const BruteKnex = require('@tryghost/brute-knex');
+
+const knex = Knex({
+    client: 'mysql2',
+    connection: {
+        host: '127.0.0.1',
+        user: 'root',
+        password: 'root',
+        database: 'brute_knex'
+    }
+});
+
+const store = new BruteKnex({
+    knex,
+    tablename: 'brute'
+});
+
+const bruteforce = new ExpressBrute(store, {
+    freeRetries: 2
+});
+```
+
+See [example.js](example.js) for a complete Express route.
+
+## Options
+
+- `tablename`: table name for brute-force records. Defaults to `brute`.
+- `knex`: Knex instance to use. If omitted, `brute-knex` creates a SQLite database at `./brute-knex.sqlite`.
+- `createTable`: set to `false` when the table already exists and should not be created automatically.
+
+The table stores `key`, `firstRequest`, `lastRequest`, `lifetime`, and `count` columns. Timestamps are stored as UTC millisecond values.
+
+## Development
+
+This repo uses the organisation default Node.js `22` for local development through `.nvmrc`, and pnpm `10.x` through Corepack. Package support still starts at Node.js `20.20.0` for existing consumers.
+
+```sh
+corepack enable
+pnpm install --frozen-lockfile
+pnpm test
+pnpm lint
+```
+
+Database-specific test commands:
+
+```sh
+pnpm run test:e2e:sqlite
+pnpm run test:e2e:mysql
+pnpm run test:e2e:postgres
+```
+
+The MySQL and Postgres commands expect local test databases unless they are running inside the GitHub Actions service containers. The test suite reads standard connection env vars such as `MYSQL_HOST`, `MYSQL_DATABASE`, `POSTGRES_HOST`, and `POSTGRES_DB`.
+
+## Releasing
+
+Releases are handled by [`@tryghost/pro-ship`](https://www.npmjs.com/package/@tryghost/pro-ship):
+
+```sh
+pnpm ship
+```
+
+The `ship` script bumps the version, creates the release commit and tag, pushes them, and publishes `@tryghost/brute-knex` to npm.
+
+## Copyright & License
+
+Copyright (c) 2014, llambda <xxgsoftware@gmail.com>.
+Released under the [ISC license](LICENSE).
+
+[npm-version-image]: https://img.shields.io/npm/v/@tryghost/brute-knex.svg
+[npm-downloads-image]: https://img.shields.io/npm/dm/@tryghost/brute-knex.svg
+[npm-image]: https://nodei.co/npm/@tryghost/brute-knex.png?downloads=true&downloadRank=true&stars=true
+[npm-url]: https://npmjs.org/package/@tryghost/brute-knex
+[node-image]: https://img.shields.io/node/v/@tryghost/brute-knex.svg
+[node-url]: https://nodejs.org/download/

package/index.d.ts

@@ -0,0 +1,59 @@
+import type { Knex } from 'knex';
+
+declare namespace KnexStore {
+    type TimestampInput = Date | number | string;
+
+    interface StoredValueInput {
+        count: number;
+        firstRequest: TimestampInput;
+        lastRequest: TimestampInput;
+    }
+
+    interface StoredValue {
+        count: number;
+        firstRequest: Date;
+        lastRequest: Date;
+    }
+
+    interface Options {
+        createTable?: boolean;
+        knex?: Knex;
+        tablename?: string;
+    }
+
+    interface Defaults {
+        createTable: boolean;
+        tablename: string;
+    }
+
+    type ResultCallback<TResult = unknown> = (error: Error | null, result?: TResult) => void;
+    type GetCallback = (error: Error | null, value?: StoredValue | null) => void;
+}
+
+declare class KnexStore {
+    static defaults: KnexStore.Defaults;
+    static defaultsKnex: Knex.Config;
+
+    constructor(options?: KnexStore.Options);
+
+    knex: Knex;
+    options: KnexStore.Options & KnexStore.Defaults;
+    ready: Promise<void>;
+
+    set(
+        key: string,
+        value: KnexStore.StoredValueInput,
+        lifetime: number,
+        callback?: KnexStore.ResultCallback,
+    ): Promise<unknown>;
+
+    get(key: string, callback?: KnexStore.GetCallback): Promise<KnexStore.StoredValue | null>;
+
+    reset(key: string, callback?: KnexStore.ResultCallback): Promise<unknown>;
+
+    increment(key: string, lifetime: number, callback?: KnexStore.ResultCallback): Promise<unknown>;
+
+    clearExpired(callback?: KnexStore.ResultCallback): Promise<unknown>;
+}
+
+export = KnexStore;

package/index.js

@@ -0,0 +1,188 @@
+'use strict';
+var AbstractClientStore = require('express-brute/lib/AbstractClientStore');
+var _ = require('lodash');
+
+function rethrowAsync(error) {
+    setTimeout(function () {
+        throw error;
+    }, 0);
+}
+
+function withCallback(promise, callback) {
+    promise = Promise.resolve(promise);
+
+    if (typeof callback === 'function') {
+        var callbackPromise = promise.then(
+            function (result) {
+                callback(null, result);
+            },
+            function (error) {
+                callback(error);
+            },
+        );
+
+        callbackPromise.catch(rethrowAsync);
+    }
+
+    return promise;
+}
+
+/**
+ * we are using bigInteger to store a UTC timestamp
+ * alternative would be using moment-timezone to store YYYY-MM-DD HH:mm:ss (but it does not contain ms)
+ *
+ * @type {module.exports}
+ */
+var KnexStore = (module.exports = function (options) {
+    var self = this;
+
+    options = options || {};
+
+    AbstractClientStore.apply(this, arguments);
+    this.options = _.extend({}, KnexStore.defaults, options);
+
+    if (this.options.knex) {
+        this.knex = this.options.knex;
+    } else {
+        this.knex = require('knex')(KnexStore.defaultsKnex);
+    }
+
+    if (options.createTable === false) {
+        self.ready = Promise.resolve();
+    } else {
+        self.ready = self.knex.schema.hasTable(self.options.tablename).then(function (exists) {
+            if (!exists) {
+                return self.knex.schema.createTable(self.options.tablename, function (table) {
+                    table.string('key');
+                    table.bigInteger('firstRequest').nullable();
+                    table.bigInteger('lastRequest').nullable();
+                    table.bigInteger('lifetime').nullable();
+                    table.integer('count');
+                });
+            }
+        });
+    }
+
+    self.ready = Promise.resolve(self.ready);
+});
+KnexStore.prototype = Object.create(AbstractClientStore.prototype);
+
+KnexStore.prototype.set = function (key, value, lifetime, callback) {
+    var self = this;
+    lifetime = lifetime || 0;
+
+    return withCallback(
+        self.ready.then(function () {
+            return self.knex.transaction(function (trx) {
+                return trx
+                    .select('*')
+                    .forUpdate()
+                    .from(self.options.tablename)
+                    .where('key', '=', key)
+                    .then(function (foundKeys) {
+                        if (foundKeys.length == 0) {
+                            return trx.from(self.options.tablename).insert({
+                                key: key,
+                                lifetime: new Date(Date.now() + lifetime * 1000).getTime(),
+                                lastRequest: new Date(value.lastRequest).getTime(),
+                                firstRequest: new Date(value.firstRequest).getTime(),
+                                count: value.count,
+                            });
+                        } else {
+                            return trx(self.options.tablename)
+                                .where('key', '=', key)
+                                .update({
+                                    lifetime: new Date(Date.now() + lifetime * 1000).getTime(),
+                                    count: value.count,
+                                    lastRequest: new Date(value.lastRequest).getTime(),
+                                });
+                        }
+                    });
+            });
+        }),
+        callback,
+    );
+};
+
+KnexStore.prototype.get = function (key, callback) {
+    var self = this;
+    return withCallback(
+        self.ready
+            .then(function () {
+                return self.clearExpired();
+            })
+            .then(function () {
+                return self.knex.select('*').from(self.options.tablename).where('key', '=', key);
+            })
+            .then(function (response) {
+                var o = null;
+                if (response[0]) {
+                    o = {};
+                    o.lastRequest = new Date(response[0].lastRequest);
+                    o.firstRequest = new Date(response[0].firstRequest);
+                    o.count = response[0].count;
+                }
+                return o;
+            }),
+        callback,
+    );
+};
+KnexStore.prototype.reset = function (key, callback) {
+    var self = this;
+    return withCallback(
+        self.ready.then(function () {
+            return self.knex(self.options.tablename).where('key', '=', key).del();
+        }),
+        callback,
+    );
+};
+
+KnexStore.prototype.increment = function (key, lifetime, callback) {
+    var self = this;
+    return withCallback(
+        self.get(key).then(function (result) {
+            if (result) {
+                return self
+                    .knex(self.options.tablename)
+                    .increment('count', 1)
+                    .where('key', '=', key);
+            } else {
+                return self.knex(self.options.tablename).insert({
+                    key: key,
+                    firstRequest: new Date().getTime(),
+                    lastRequest: new Date().getTime(),
+                    lifetime: new Date(Date.now() + lifetime * 1000).getTime(),
+                    count: 1,
+                });
+            }
+        }),
+        callback,
+    );
+};
+
+KnexStore.prototype.clearExpired = function (callback) {
+    var self = this;
+    return withCallback(
+        self.ready.then(function () {
+            return self
+                .knex(self.options.tablename)
+                .del()
+                .where('lifetime', '<', new Date().getTime());
+        }),
+        callback,
+    );
+};
+
+KnexStore.defaults = {
+    tablename: 'brute',
+    createTable: true,
+};
+
+KnexStore.defaultsKnex = {
+    client: 'sqlite3',
+    // debug: true,
+    connection: {
+        filename: './brute-knex.sqlite',
+    },
+    useNullAsDefault: true,
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@tryghost/brute-knex",
+  "version": "3.0.0",
+  "description": "A Knex.js store for express-brute",
+  "keywords": [
+    "express",
+    "brute",
+    "knex"
+  ],
+  "license": "ISC",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.20.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:TryGhost/brute-knex.git"
+  },
+  "devDependencies": {
+    "@tryghost/pro-ship": "1.1.4",
+    "@vitest/coverage-v8": "4.1.9",
+    "mysql2": "3.22.5",
+    "oxfmt": "0.56.0",
+    "oxlint": "1.71.0",
+    "pg": "8.22.0",
+    "sqlite3": "6.0.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.9"
+  },
+  "dependencies": {
+    "express-brute": "1.0.1",
+    "knex": "2.5.1",
+    "lodash": "4.18.1"
+  },
+  "scripts": {
+    "format": "oxfmt .",
+    "lint": "oxlint --quiet && oxfmt --check . && pnpm run test:types",
+    "lint:fix": "oxlint --fix && oxfmt .",
+    "preship": "pnpm lint && pnpm test",
+    "ship": "pro-ship --publish",
+    "test": "vitest run --coverage",
+    "test:e2e:sqlite": "BRUTE_KNEX_DIALECTS=sqlite vitest run --coverage",
+    "test:e2e:mysql": "BRUTE_KNEX_DIALECTS=mysql vitest run --coverage",
+    "test:e2e:postgres": "BRUTE_KNEX_DIALECTS=postgres vitest run --coverage",
+    "test:types": "tsc --noEmit -p tsconfig.types.json"
+  }
+}