@zintrust/core 0.1.17 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/core",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Production-grade TypeScript backend framework for JavaScript",
   "homepage": "https://zintrust.com",
   "repository": {

package/src/cli/PromptHelper.js

@@ -63,7 +63,7 @@ export const PromptHelper = Object.freeze({
     /**
      * Ask for port number
      */
-    async port(defaultPort = 3000, interactive = true) {
+    async port(defaultPort = 7777, interactive = true) {
         if (!interactive) {
             return defaultPort;
         }

package/src/cli/commands/NewCommand.js

@@ -54,7 +54,7 @@ const getProjectDefaults = (name, options) => {
     const database = getStringOption(options, 'database', 'sqlite');
     const portRaw = getStringOption(options, 'port', '7777');
     const portParsed = Number.parseInt(portRaw, 10);
-    const port = Number.isFinite(portParsed) && portParsed > 0 ? portParsed : 3000;
+    const port = Number.isFinite(portParsed) && portParsed > 0 ? portParsed : 7777;
     const author = getStringOption(options, 'author', '');
     const description = getStringOption(options, 'description', `A new Zintrust project: ${name}`);
     const interactive = getBooleanOption(options, 'interactive', true);

package/src/cli/config/ConfigSchema.js

@@ -18,7 +18,7 @@ export const DEFAULT_CONFIG = Object.freeze({
         logging: false,
     },
     server: {
-        port: 3000,
+        port: 7777,
         host: '0.0.0.0',
         environment: 'development',
         debug: false,

package/src/cli/scaffolding/ProjectScaffolder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProjectScaffolder.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/ProjectScaffolder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtD,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,eAAe,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IACpE,cAAc,IAAI,MAAM,CAAC;IACzB,sBAAsB,IAAI,OAAO,CAAC;IAClC,iBAAiB,IAAI,MAAM,CAAC;IAC5B,WAAW,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAAC;IACtD,gBAAgB,IAAI,OAAO,CAAC;IAC5B,aAAa,IAAI,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAC3E;AAyaD,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAsBrE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG;IAChE,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAsBA;AA0ID;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,GAAE,MAAsB,GAAG,kBAAkB,CAsB/F;AAED,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAEhC;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;EAM5B,CAAC"}
+{"version":3,"file":"ProjectScaffolder.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/ProjectScaffolder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtD,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,eAAe,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IACpE,cAAc,IAAI,MAAM,CAAC;IACzB,sBAAsB,IAAI,OAAO,CAAC;IAClC,iBAAiB,IAAI,MAAM,CAAC;IAC5B,WAAW,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAAC;IACtD,gBAAgB,IAAI,OAAO,CAAC;IAC5B,aAAa,IAAI,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAC3E;AAsfD,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAsBrE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG;IAChE,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAsBA;AA0ID;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,GAAE,MAAsB,GAAG,kBAAkB,CAsB/F;AAED,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAEhC;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;EAM5B,CAAC"}

package/src/cli/scaffolding/ProjectScaffolder.js

@@ -87,7 +87,7 @@ const createProjectConfigFile = (projectPath, variables) => {
                 connection: variables['database'] ?? 'sqlite',
             },
             server: {
-                port: variables['port'] ?? 3000,
+                port: variables['port'] ?? 7777,
             },
         };
         fs.writeFileSync(fullPath, JSON.stringify(config, null, 2));
@@ -97,18 +97,96 @@ const createProjectConfigFile = (projectPath, variables) => {
         return false;
     }
 };
+const stripEnvInlineComment = (value) => {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < value.length; i += 1) {
+        const ch = value[i];
+        if (ch === "'" && !inDouble)
+            inSingle = !inSingle;
+        if (ch === '"' && !inSingle)
+            inDouble = !inDouble;
+        if (!inSingle && !inDouble && ch === '#') {
+            const prev = value[i - 1];
+            if (prev === undefined || prev === ' ' || prev === '\t') {
+                return value.slice(0, i).trimEnd();
+            }
+        }
+    }
+    return value;
+};
+const backfillEnvDefaults = (envPath, defaults) => {
+    const raw = fs.readFileSync(envPath, 'utf8');
+    const lines = raw.split(/\r?\n/);
+    const seen = new Set();
+    const filled = new Set();
+    const out = lines.map((line) => {
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            return line;
+        const withoutExport = trimmed.startsWith('export ') ? trimmed.slice('export '.length) : trimmed;
+        const eq = withoutExport.indexOf('=');
+        if (eq <= 0)
+            return line;
+        const key = withoutExport.slice(0, eq).trim();
+        if (key === '')
+            return line;
+        if (!Object.hasOwn(defaults, key))
+            return line;
+        if (seen.has(key))
+            return line;
+        seen.add(key);
+        const rhs = withoutExport.slice(eq + 1);
+        const withoutComment = stripEnvInlineComment(rhs);
+        const value = withoutComment.trim();
+        if (value !== '')
+            return line;
+        filled.add(key);
+        return `${key}=${defaults[key]}`;
+    });
+    const missingKeys = Object.keys(defaults).filter((k) => !seen.has(k));
+    if (missingKeys.length > 0) {
+        out.push(...missingKeys.map((k) => `${k}=${defaults[k]}`));
+    }
+    // Avoid rewriting if nothing changed.
+    if (filled.size === 0 && missingKeys.length === 0)
+        return;
+    fs.writeFileSync(envPath, out.join('\n') + (out.at(-1) === '' ? '' : '\n'));
+};
+const buildDatabaseEnvLines = (database) => {
+    if (database === 'postgresql' || database === 'postgres') {
+        return [
+            'DB_HOST=localhost',
+            'DB_PORT=5432',
+            'DB_DATABASE=zintrust',
+            'DB_USERNAME=postgres',
+            'DB_PASSWORD=',
+        ];
+    }
+    if (database === 'sqlite') {
+        // Provide both DB_DATABASE (used by the framework) and DB_PATH (common alias)
+        return ['DB_DATABASE=./database.sqlite', 'DB_PATH=./database.sqlite'];
+    }
+    return [];
+};
 const createEnvFile = (projectPath, variables) => {
     try {
         if (!fs.existsSync(projectPath)) {
             fs.mkdirSync(projectPath, { recursive: true });
         }
         const fullPath = path.join(projectPath, '.env');
-        // If the template already produced an .env, do not overwrite it here.
+        // If an .env already exists (e.g., from a template), do not overwrite user values.
+        // But we *do* backfill safe defaults for common bootstrap keys when missing/blank.
         if (fs.existsSync(fullPath)) {
+            backfillEnvDefaults(fullPath, {
+                HOST: 'localhost',
+                PORT: String(Number(variables['port'] ?? 7777)),
+                LOG_LEVEL: 'debug',
+            });
             return true;
         }
         const name = typeof variables['projectName'] === 'string' ? variables['projectName'] : 'zintrust-app';
-        const port = Number(variables['port'] ?? 3000);
+        const port = Number(variables['port'] ?? 7777);
         const database = typeof variables['database'] === 'string' ? variables['database'] : 'sqlite';
         // Generate a secure APP_KEY (32 bytes = 256-bit, base64 encoded)
         const appKeyBytes = randomBytes(32);
@@ -125,22 +203,7 @@ const createEnvFile = (projectPath, variables) => {
             `APP_KEY=${appKey}`,
             `DB_CONNECTION=${database}`,
         ];
-        const dbLines = (() => {
-            if (database === 'postgresql' || database === 'postgres') {
-                return [
-                    'DB_HOST=localhost',
-                    'DB_PORT=5432',
-                    'DB_DATABASE=zintrust',
-                    'DB_USERNAME=postgres',
-                    'DB_PASSWORD=',
-                ];
-            }
-            if (database === 'sqlite') {
-                // Provide both DB_DATABASE (used by the framework) and DB_PATH (common alias)
-                return ['DB_DATABASE=./database.sqlite', 'DB_PATH=./database.sqlite'];
-            }
-            return [];
-        })();
+        const dbLines = buildDatabaseEnvLines(database);
         const placeholderLines = [
             '',
             '# Logging',
@@ -245,11 +308,15 @@ const loadTemplateFiles = (templateDir) => {
         if (relPath === 'template.json')
             return false;
         const normalized = normalizeRelPath(relPath);
+        // Project `.env` is generated by createEnvFile() so it can set defaults and create a secure APP_KEY.
+        // Some templates ship `.env.tpl` (which would become `.env`), but that file is intentionally ignored.
+        const outputRel = normalizeRelPath(getOutputRelPath(relPath));
+        if (outputRel === '.env')
+            return false;
         if (!normalized.startsWith('config/'))
             return true;
         // Starter apps should only ship app-level config modules.
         // Core/framework config internals (e.g. config/logging/*) remain core-owned.
-        const outputRel = normalizeRelPath(getOutputRelPath(relPath));
         return allowedConfigFiles.has(outputRel);
     };
     const readUtf8FileOrUndefined = (absPath) => {
@@ -424,7 +491,7 @@ const prepareContext = (state, options) => {
         projectSlug: options.name,
         author: options.author ?? 'Your Name',
         description: options.description ?? '',
-        port: options.port ?? 3000,
+        port: options.port ?? 7777,
         database: options.database ?? 'sqlite',
         template: state.templateName,
         migrationTimestamp,

package/src/middleware/RateLimiter.d.ts

@@ -12,8 +12,43 @@ export interface RateLimitOptions {
     statusCode?: number;
     headers?: boolean;
     keyGenerator?: (req: IRequest) => string;
+    /**
+     * Optional store selection for this middleware instance.
+     * - 'memory' uses an in-process Map (default)
+     * - 'redis' uses Cache.store('redis')
+     * - 'kv' uses Cache.store('kv')
+     * - 'db' uses Cache.store('mongodb')
+     */
+    store?: RateLimitStoreName;
 }
+export type RateLimitStoreName = 'memory' | 'redis' | 'kv' | 'db';
 export declare const RateLimiter: Readonly<{
+    /**
+     * Configure the store used by the programmatic API (attempt/tooManyAttempts/till/clear).
+     * Defaults to 'memory'.
+     */
+    configure(config?: {
+        store?: RateLimitStoreName;
+    }): void;
+    /**
+     * Attempt to perform an action.
+     *
+     * Returns true if allowed (and records the hit), false if rate limited.
+     */
+    attempt(key: string, maxAttempts: number, decaySeconds: number): Promise<boolean>;
+    /**
+     * Check if the key is currently rate limited.
+     */
+    tooManyAttempts(key: string, maxAttempts: number): Promise<boolean>;
+    /**
+     * Seconds until the key is available again.
+     * Returns 0 if not rate limited.
+     */
+    till(key: string): Promise<number>;
+    /**
+     * Clear rate limit state for a key.
+     */
+    clear(key: string): Promise<void>;
     /**
      * Create rate limiter middleware
      */

package/src/middleware/RateLimiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RateLimiter.d.ts","sourceRoot":"","sources":["../../../src/middleware/RateLimiter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,MAAM,CAAC;CAC1C;AAoBD,eAAO,MAAM,WAAW;IACtB;;OAEG;qBACa,gBAAgB,GAAqB,UAAU;EA4D/D,CAAC"}
+{"version":3,"file":"RateLimiter.d.ts","sourceRoot":"","sources":["../../../src/middleware/RateLimiter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,MAAM,CAAC;IAEzC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC5B;AAED,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,CAAC;AAyIlE,eAAO,MAAM,WAAW;IACtB;;;OAGG;uBACgB;QAAE,KAAK,CAAC,EAAE,kBAAkB,CAAA;KAAE,GAAG,IAAI;IAKxD;;;;OAIG;iBACgB,MAAM,eAAe,MAAM,gBAAgB,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYvF;;OAEG;yBACwB,MAAM,eAAe,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQzE;;;OAGG;cACa,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQxC;;OAEG;eACc,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvC;;OAEG;qBACa,gBAAgB,GAAqB,UAAU;EAgF/D,CAAC"}

package/src/middleware/RateLimiter.js

@@ -3,7 +3,104 @@
  * Token bucket implementation for request rate limiting
  * Zero-dependency implementation
  */
+import { Cache } from '../cache/Cache.js';
 import { Logger } from '../config/logger.js';
+const createMemoryStore = () => {
+    const entries = new Map();
+    let nextCleanupAt = Date.now() + 60_000;
+    const cleanupExpired = (now) => {
+        if (now < nextCleanupAt)
+            return;
+        for (const [k, state] of entries.entries()) {
+            if (now > state.resetTime)
+                entries.delete(k);
+        }
+        nextCleanupAt = now + 60_000;
+    };
+    return Object.freeze({
+        async get(key) {
+            await Promise.resolve();
+            const now = Date.now();
+            cleanupExpired(now);
+            const state = entries.get(key);
+            if (!state)
+                return null;
+            if (now > state.resetTime) {
+                entries.delete(key);
+                return null;
+            }
+            return { ...state };
+        },
+        async set(key, value) {
+            await Promise.resolve();
+            const now = Date.now();
+            cleanupExpired(now);
+            entries.set(key, { ...value });
+        },
+        async delete(key) {
+            await Promise.resolve();
+            entries.delete(key);
+        },
+    });
+};
+const createCacheStore = (storeName) => {
+    const store = Cache.store(storeName);
+    return Object.freeze({
+        async get(key) {
+            return store.get(key);
+        },
+        async set(key, value, ttlSeconds) {
+            await store.set(key, value, ttlSeconds);
+        },
+        async delete(key) {
+            await store.delete(key);
+        },
+    });
+};
+const normalizeStoreName = (name) => {
+    const raw = String(name ?? '')
+        .trim()
+        .toLowerCase();
+    if (raw === 'redis')
+        return 'redis';
+    if (raw === 'kv')
+        return 'kv';
+    if (raw === 'db' || raw === 'database' || raw === 'mongo' || raw === 'mongodb')
+        return 'db';
+    return 'memory';
+};
+const resolveStore = (name) => {
+    const selected = normalizeStoreName(name ?? process.env['RATE_LIMIT_STORE'] ?? process.env['RATE_LIMIT_DRIVER'] ?? 'memory');
+    if (selected === 'redis')
+        return { storeName: 'redis', store: createCacheStore('redis') };
+    if (selected === 'kv')
+        return { storeName: 'kv', store: createCacheStore('kv') };
+    if (selected === 'db')
+        return { storeName: 'db', store: createCacheStore('mongodb') };
+    return { storeName: 'memory', store: createMemoryStore() };
+};
+let serviceStoreSelection = normalizeStoreName(process.env['RATE_LIMIT_STORE'] ?? process.env['RATE_LIMIT_DRIVER'] ?? 'memory');
+let serviceStore = resolveStore(serviceStoreSelection).store;
+const prefixKey = (purpose, key) => {
+    const prefix = (process.env['RATE_LIMIT_KEY_PREFIX'] ?? 'zintrust:ratelimit:').toString().trim();
+    return `${prefix}${purpose}:${key}`;
+};
+const consume = async (params) => {
+    const now = Date.now();
+    const ttlSeconds = Math.max(1, Math.ceil(params.windowMs / 1000));
+    const existing = await params.store.get(params.key);
+    const state = existing === null || now > existing.resetTime
+        ? { count: 0, resetTime: now + params.windowMs }
+        : existing;
+    const nextCount = state.count + 1;
+    const nextState = { count: nextCount, resetTime: state.resetTime };
+    await params.store.set(params.key, nextState, ttlSeconds);
+    return {
+        count: nextCount,
+        resetTime: nextState.resetTime,
+        allowed: nextCount <= params.max,
+    };
+};
 const DEFAULT_OPTIONS = {
     windowMs: 60 * 1000, // 1 minute
     max: 100, // 100 requests per minute
@@ -15,11 +112,68 @@ const DEFAULT_OPTIONS = {
     },
 };
 export const RateLimiter = Object.freeze({
+    /**
+     * Configure the store used by the programmatic API (attempt/tooManyAttempts/till/clear).
+     * Defaults to 'memory'.
+     */
+    configure(config) {
+        serviceStoreSelection = normalizeStoreName(config?.store);
+        serviceStore = resolveStore(serviceStoreSelection).store;
+    },
+    /**
+     * Attempt to perform an action.
+     *
+     * Returns true if allowed (and records the hit), false if rate limited.
+     */
+    async attempt(key, maxAttempts, decaySeconds) {
+        const windowMs = Math.max(1, Math.floor(decaySeconds * 1000));
+        const namespacedKey = prefixKey('service', key);
+        const out = await consume({
+            store: serviceStore,
+            key: namespacedKey,
+            max: maxAttempts,
+            windowMs,
+        });
+        return out.allowed;
+    },
+    /**
+     * Check if the key is currently rate limited.
+     */
+    async tooManyAttempts(key, maxAttempts) {
+        const now = Date.now();
+        const namespacedKey = prefixKey('service', key);
+        const state = await serviceStore.get(namespacedKey);
+        if (!state || now > state.resetTime)
+            return false;
+        return state.count >= maxAttempts;
+    },
+    /**
+     * Seconds until the key is available again.
+     * Returns 0 if not rate limited.
+     */
+    async till(key) {
+        const now = Date.now();
+        const namespacedKey = prefixKey('service', key);
+        const state = await serviceStore.get(namespacedKey);
+        if (!state || now > state.resetTime)
+            return 0;
+        return Math.max(0, Math.ceil((state.resetTime - now) / 1000));
+    },
+    /**
+     * Clear rate limit state for a key.
+     */
+    async clear(key) {
+        const namespacedKey = prefixKey('service', key);
+        await serviceStore.delete(namespacedKey);
+    },
     /**
      * Create rate limiter middleware
      */
     create(options = DEFAULT_OPTIONS) {
         const config = { ...DEFAULT_OPTIONS, ...options };
+        const { storeName, store } = resolveStore(config.store);
+        const useMemoryInstanceStore = storeName === 'memory';
+        // Middleware store is per-instance (matches prior behavior).
         const clients = new Map();
         // Cleanup to prevent unbounded growth.
         // Done lazily (on requests) to avoid background timers in serverless/test environments.
@@ -27,29 +181,47 @@ export const RateLimiter = Object.freeze({
         const cleanupExpiredClients = (now) => {
             if (now < nextCleanupAt)
                 return;
-            for (const [key, state] of clients.entries()) {
+            for (const [k, state] of clients.entries()) {
                 if (now > state.resetTime) {
-                    clients.delete(key);
+                    clients.delete(k);
                 }
             }
             nextCleanupAt = now + config.windowMs;
         };
-        return async (req, res, next) => {
-            const key = config.keyGenerator ? config.keyGenerator(req) : 'unknown';
-            const now = Date.now();
-            cleanupExpiredClients(now);
+        const getOrInitClient = (key, now) => {
             let client = clients.get(key);
-            // Initialize or reset if window expired
             if (!client || now > client.resetTime) {
-                client = {
-                    count: 0,
-                    resetTime: now + config.windowMs,
-                };
+                client = { count: 0, resetTime: now + config.windowMs };
                 clients.set(key, client);
             }
-            client.count++;
-            const remaining = Math.max(0, config.max - client.count);
-            const resetTime = Math.ceil((client.resetTime - now) / 1000);
+            return client;
+        };
+        return async (req, res, next) => {
+            const key = config.keyGenerator ? config.keyGenerator(req) : 'unknown';
+            const now = Date.now();
+            let count;
+            let resetAt;
+            if (useMemoryInstanceStore) {
+                cleanupExpiredClients(now);
+                const client = getOrInitClient(key, now);
+                client.count++;
+                count = client.count;
+                resetAt = client.resetTime;
+            }
+            else {
+                // Include limiter config to avoid collisions between different middleware instances.
+                const middlewareKey = prefixKey('middleware', `${config.max}:${config.windowMs}:${key}`);
+                const out = await consume({
+                    store,
+                    key: middlewareKey,
+                    max: config.max,
+                    windowMs: config.windowMs,
+                });
+                count = out.count;
+                resetAt = out.resetTime;
+            }
+            const remaining = Math.max(0, config.max - count);
+            const resetTime = Math.ceil((resetAt - now) / 1000);
             // Set headers
             if (config.headers ?? false) {
                 res.setHeader('X-RateLimit-Limit', config.max.toString());
@@ -57,7 +229,7 @@ export const RateLimiter = Object.freeze({
                 res.setHeader('X-RateLimit-Reset', resetTime.toString());
             }
             // Check limit
-            if (client.count > config.max) {
+            if (count > config.max) {
                 Logger.warn(`Rate limit exceeded for IP: ${key}`);
                 res.setStatus(config.statusCode ?? 429);
                 res.json({