@nauth-toolkit/core 0.2.7 → 0.3.1

package/dist/services/telemetry.service.js

@@ -0,0 +1,345 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryService = void 0;
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const get_package_version_1 = require("../utils/get-package-version");
+/**
+ * Default telemetry ingestion endpoint (stable custom domain; the deployment
+ * behind it can change without a package release).
+ */
+const DEFAULT_ENDPOINT = 'https://telemetry.nauth.dev/';
+/** Storage key holding the shared anonymous instance identifier. */
+const INSTANCE_ID_KEY = 'nauth:telemetry:instance_id';
+/** Network timeout for telemetry requests — beyond this the request is aborted. */
+const SEND_TIMEOUT_MS = 3000;
+/** Heartbeat base interval (24h); a random jitter of up to 1h is added per process. */
+const HEARTBEAT_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const HEARTBEAT_JITTER_MS = 60 * 60 * 1000;
+/**
+ * Anonymous usage telemetry (opt-out)
+ *
+ * Sends a small, anonymous payload describing the *shape* of the nauth
+ * configuration (enums, booleans, and registered provider names — never
+ * values) once at boot and once per day thereafter. The data guides
+ * development priorities; see https://nauth.dev/docs/concepts/telemetry
+ * for the exact payload and rationale.
+ *
+ * **Performance guarantees:**
+ * - Never runs inside a request path — no middleware or handler involvement
+ * - The boot ping is deferred and fire-and-forget; `NAuth.create()` gains no awaits
+ * - The heartbeat timer is unref'd and never keeps the process alive
+ * - Network failures are swallowed at debug level; this service never throws
+ *
+ * **Disabled automatically** when any of the following holds:
+ * - `config.telemetry.enabled === false`
+ * - `NAUTH_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1`
+ * - `CI=true` or `NODE_ENV=test`
+ *
+ * @example
+ * ```typescript
+ * const telemetry = new TelemetryService(config, storage, logger, 'express', mfaService, socialRegistry);
+ * telemetry.sendBootPing();
+ * telemetry.startHeartbeat();
+ * // ...on shutdown:
+ * telemetry.shutdown();
+ * ```
+ */
+class TelemetryService {
+    config;
+    storageAdapter;
+    logger;
+    framework;
+    mfaService;
+    socialProviderRegistry;
+    heartbeatTimer;
+    cachedInstanceId;
+    disclosureShown = false;
+    constructor(config, storageAdapter, logger, framework = 'unknown', mfaService, socialProviderRegistry) {
+        this.config = config;
+        this.storageAdapter = storageAdapter;
+        this.logger = logger;
+        this.framework = framework;
+        this.mfaService = mfaService;
+        this.socialProviderRegistry = socialProviderRegistry;
+    }
+    /**
+     * Whether telemetry is active for this process.
+     *
+     * Evaluates the config flag and all environment opt-outs
+     * (NAUTH_TELEMETRY_DISABLED, DO_NOT_TRACK, CI, NODE_ENV=test).
+     *
+     * @returns true when telemetry may be sent
+     */
+    isEnabled() {
+        if (this.config.telemetry?.enabled === false) {
+            return false;
+        }
+        const env = process.env;
+        const truthy = (v) => v === '1' || v?.toLowerCase() === 'true';
+        if (truthy(env.NAUTH_TELEMETRY_DISABLED) || truthy(env.DO_NOT_TRACK)) {
+            return false;
+        }
+        if (env.CI !== undefined && env.CI !== '' && env.CI.toLowerCase() !== 'false') {
+            return false;
+        }
+        if (env.NODE_ENV === 'test') {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Send the boot ping (fire-and-forget).
+     *
+     * On the first boot of an install (when the anonymous instance ID is
+     * created), a one-time disclosure notice is logged. Subsequent boots of
+     * the same install are silent. This method returns immediately and never
+     * throws; all work happens off the startup path.
+     */
+    sendBootPing() {
+        if (!this.isEnabled()) {
+            return;
+        }
+        this.resolveInstanceId()
+            .then(({ instanceId, isNew }) => {
+            if (isNew && !this.disclosureShown) {
+                this.disclosureShown = true;
+                this.logger?.log?.('nauth-toolkit collects anonymous usage data (config shape only — no PII, IPs, or secrets) to guide development. ' +
+                    'Details and opt-out: https://nauth.dev/docs/concepts/telemetry (set NAUTH_TELEMETRY_DISABLED=1 to disable)');
+            }
+            return this.send(this.buildPayload('boot', instanceId));
+        })
+            .catch((err) => {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            this.logger?.debug?.(`Telemetry boot ping skipped: ${message}`);
+        });
+    }
+    /**
+     * Start the daily heartbeat timer.
+     *
+     * The timer is unref'd so it never prevents process exit. A random jitter
+     * of up to one hour avoids synchronized pings from fleets that restart
+     * together. No-op when telemetry is disabled.
+     */
+    startHeartbeat() {
+        if (!this.isEnabled() || this.heartbeatTimer) {
+            return;
+        }
+        const interval = HEARTBEAT_INTERVAL_MS + Math.floor(Math.random() * HEARTBEAT_JITTER_MS);
+        this.heartbeatTimer = setInterval(() => {
+            this.resolveInstanceId()
+                .then(({ instanceId }) => this.send(this.buildPayload('heartbeat', instanceId)))
+                .catch((err) => {
+                const message = err instanceof Error ? err.message : 'Unknown error';
+                this.logger?.debug?.(`Telemetry heartbeat skipped: ${message}`);
+            });
+        }, interval);
+        this.heartbeatTimer.unref?.();
+    }
+    /**
+     * Stop the heartbeat timer. Safe to call multiple times.
+     */
+    shutdown() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+    }
+    /**
+     * Resolve the anonymous instance ID, with layered persistence:
+     *
+     * 1. **Storage adapter** (Redis/database) — deployment-scoped: all processes
+     *    sharing the deployment converge on one ID via an NX (set-if-absent) write.
+     * 2. **Home-directory file** (`~/.nauth-toolkit/telemetry-instance-id`) — used
+     *    when the storage adapter is the non-persistent in-memory adapter, so
+     *    restarts on the same machine keep one ID instead of minting a new
+     *    "install" per boot.
+     * 3. **Per-process UUID** — last resort when both stores are unavailable
+     *    (e.g. read-only filesystem); never throws.
+     *
+     * `isNew` is true only when this process created the ID — used to show the
+     * disclosure notice exactly once per install.
+     */
+    async resolveInstanceId() {
+        if (this.cachedInstanceId) {
+            return { instanceId: this.cachedInstanceId, isNew: false };
+        }
+        try {
+            // The first get() also initializes lazy wrappers, so the unwrapped
+            // adapter name below is accurate.
+            const existing = await this.storageAdapter.get(INSTANCE_ID_KEY);
+            // In-memory storage does not survive restarts — prefer the file store
+            // so an install keeps a stable identity across boots.
+            if (!this.storageAdapterName().toLowerCase().includes('memory')) {
+                if (existing) {
+                    this.cachedInstanceId = existing;
+                    return { instanceId: existing, isNew: false };
+                }
+                const candidate = (0, crypto_1.randomUUID)();
+                await this.storageAdapter.set(INSTANCE_ID_KEY, candidate, undefined, { nx: true });
+                const settled = (await this.storageAdapter.get(INSTANCE_ID_KEY)) ?? candidate;
+                this.cachedInstanceId = settled;
+                return { instanceId: settled, isNew: settled === candidate };
+            }
+        }
+        catch {
+            // Storage unavailable — fall through to the file store.
+        }
+        return this.resolveInstanceIdFromFile();
+    }
+    /**
+     * File-backed instance ID under the user's home directory. Returns a
+     * per-process UUID when the filesystem is unavailable or read-only.
+     */
+    resolveInstanceIdFromFile() {
+        try {
+            const dir = path.join(os.homedir(), '.nauth-toolkit');
+            const file = path.join(dir, 'telemetry-instance-id');
+            const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8').trim() : '';
+            if (/^[0-9a-f-]{36}$/i.test(existing)) {
+                this.cachedInstanceId = existing;
+                return { instanceId: existing, isNew: false };
+            }
+            const candidate = (0, crypto_1.randomUUID)();
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(file, candidate, 'utf8');
+            this.cachedInstanceId = candidate;
+            return { instanceId: candidate, isNew: true };
+        }
+        catch {
+            const fallback = (0, crypto_1.randomUUID)();
+            this.cachedInstanceId = fallback;
+            return { instanceId: fallback, isNew: true };
+        }
+    }
+    /**
+     * Build the telemetry payload from the resolved configuration and the
+     * registered provider lists. Pure shape extraction — no values are read
+     * beyond enums, booleans, and provider identifiers.
+     */
+    buildPayload(event, instanceId) {
+        const cfg = this.config;
+        const nodeEnv = process.env.NODE_ENV === 'production'
+            ? 'production'
+            : process.env.NODE_ENV === 'development' || process.env.NODE_ENV === undefined
+                ? 'development'
+                : 'other';
+        let mfaProviders = [];
+        try {
+            mfaProviders = this.mfaService?.listProviders().providers ?? [];
+        }
+        catch {
+            // Provider registry unavailable — report empty rather than fail.
+        }
+        let socialProviders = [];
+        try {
+            socialProviders = this.socialProviderRegistry?.listProviders() ?? [];
+        }
+        catch {
+            // Provider registry unavailable — report empty rather than fail.
+        }
+        return {
+            schemaVersion: 1,
+            instanceId,
+            event,
+            coreVersion: (0, get_package_version_1.getCoreVersion)(),
+            nodeMajor: parseInt(process.versions.node.split('.')[0], 10),
+            platform: process.platform,
+            arch: process.arch,
+            nodeEnv,
+            framework: this.framework,
+            config: {
+                tokenDeliveryMethod: cfg.tokenDelivery?.method ?? 'json',
+                mfa: {
+                    enabled: cfg.mfa?.enabled === true,
+                    enforcement: cfg.mfa?.enforcement ?? null,
+                    gracePeriodSet: cfg.mfa?.gracePeriod !== undefined,
+                    allowedMethods: (cfg.mfa?.allowedMethods ?? []).map((m) => String(m)),
+                },
+                mfaProviders,
+                socialProviders,
+                storageAdapter: this.storageAdapterName(),
+                signupVerificationMethod: cfg.signup?.verificationMethod ?? null,
+                auditLogsEnabled: cfg.auditLogs?.enabled !== false,
+                recaptchaEnabled: cfg.recaptcha?.enabled === true,
+                geoLocationConfigured: cfg.geoLocation?.maxMind !== undefined,
+            },
+        };
+    }
+    /**
+     * Resolve the storage adapter class name for the payload.
+     *
+     * Lazy wrappers (used by the NestJS module and the core storage factory)
+     * would otherwise report 'LazyStorageAdapter' for every install; when the
+     * wrapper has an initialized inner adapter, its class name is reported
+     * instead. By the time the payload is built the instance-ID lookup has
+     * already gone through the adapter, so the inner adapter exists.
+     */
+    storageAdapterName() {
+        const wrapper = this.storageAdapter;
+        return wrapper.inner?.constructor?.name ?? this.storageAdapter.constructor.name;
+    }
+    /**
+     * POST the payload to the telemetry endpoint with a hard timeout.
+     * All failures are swallowed (debug log only) — telemetry must be
+     * invisible when it fails.
+     */
+    async send(payload) {
+        const endpoint = this.config.telemetry?.endpoint ?? DEFAULT_ENDPOINT;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), SEND_TIMEOUT_MS);
+        timeout.unref?.();
+        try {
+            await fetch(endpoint, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            this.logger?.debug?.(`Telemetry send failed (ignored): ${message}`);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+exports.TelemetryService = TelemetryService;
+//# sourceMappingURL=telemetry.service.js.map

package/dist/services/telemetry.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.service.js","sourceRoot":"","sources":["../../src/services/telemetry.service.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,mCAAoC;AACpC,uCAAyB;AACzB,uCAAyB;AACzB,2CAA6B;AAI7B,sEAA8D;AAI9D;;;GAGG;AACH,MAAM,gBAAgB,GAAG,8BAA8B,CAAC;AAExD,oEAAoE;AACpE,MAAM,eAAe,GAAG,6BAA6B,CAAC;AAEtD,mFAAmF;AACnF,MAAM,eAAe,GAAG,IAAI,CAAC;AAE7B,uFAAuF;AACvF,MAAM,qBAAqB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAClD,MAAM,mBAAmB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAqC3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAa,gBAAgB;IAMR;IACA;IACA;IACA;IACA;IACA;IAVX,cAAc,CAAkB;IAChC,gBAAgB,CAAU;IAC1B,eAAe,GAAG,KAAK,CAAC;IAEhC,YACmB,MAAmB,EACnB,cAA8B,EAC9B,MAAoB,EACpB,YAAoB,SAAS,EAC7B,UAAuB,EACvB,sBAA+C;QAL/C,WAAM,GAAN,MAAM,CAAa;QACnB,mBAAc,GAAd,cAAc,CAAgB;QAC9B,WAAM,GAAN,MAAM,CAAc;QACpB,cAAS,GAAT,SAAS,CAAoB;QAC7B,eAAU,GAAV,UAAU,CAAa;QACvB,2BAAsB,GAAtB,sBAAsB,CAAyB;IAC/D,CAAC;IAEJ;;;;;;;OAOG;IACH,SAAS;QACP,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,KAAK,KAAK,EAAE,CAAC;YAC7C,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACxB,MAAM,MAAM,GAAG,CAAC,CAAqB,EAAW,EAAE,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,WAAW,EAAE,KAAK,MAAM,CAAC;QAC5F,IAAI,MAAM,CAAC,GAAG,CAAC,wBAAwB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YACrE,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,GAAG,CAAC,EAAE,KAAK,SAAS,IAAI,GAAG,CAAC,EAAE,KAAK,EAAE,IAAI,GAAG,CAAC,EAAE,CAAC,WAAW,EAAE,KAAK,OAAO,EAAE,CAAC;YAC9E,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;YAC5B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;OAOG;IACH,YAAY;QACV,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,iBAAiB,EAAE;aACrB,IAAI,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,EAAE;YAC9B,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;gBACnC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;gBAC5B,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAChB,kHAAkH;oBAChH,4GAA4G,CAC/G,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;QAC1D,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;YACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;YACrE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,gCAAgC,OAAO,EAAE,CAAC,CAAC;QAClE,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;OAMG;IACH,cAAc;QACZ,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YAC7C,OAAO;QACT,CAAC;QACD,MAAM,QAAQ,GAAG,qBAAqB,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,mBAAmB,CAAC,CAAC;QACzF,IAAI,CAAC,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE;YACrC,IAAI,CAAC,iBAAiB,EAAE;iBACrB,IAAI,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;iBAC/E,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;gBACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;gBACrE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,gCAAgC,OAAO,EAAE,CAAC,CAAC;YAClE,CAAC,CAAC,CAAC;QACP,CAAC,EAAE,QAAQ,CAAC,CAAC;QACb,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,EAAE,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YACnC,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;QAClC,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACK,KAAK,CAAC,iBAAiB;QAC7B,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1B,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAC7D,CAAC;QACD,IAAI,CAAC;YACH,mEAAmE;YACnE,kCAAkC;YAClC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;YAChE,sEAAsE;YACtE,sDAAsD;YACtD,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAChE,IAAI,QAAQ,EAAE,CAAC;oBACb,IAAI,CAAC,gBAAgB,GAAG,QAAQ,CAAC;oBACjC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;gBAChD,CAAC;gBACD,MAAM,SAAS,GAAG,IAAA,mBAAU,GAAE,CAAC;gBAC/B,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,eAAe,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;gBACnF,MAAM,OAAO,GAAG,CAAC,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,SAAS,CAAC;gBAC9E,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC;gBAChC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,KAAK,SAAS,EAAE,CAAC;YAC/D,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,wDAAwD;QAC1D,CAAC;QACD,OAAO,IAAI,CAAC,yBAAyB,EAAE,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACK,yBAAyB;QAC/B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,gBAAgB,CAAC,CAAC;YACtD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,uBAAuB,CAAC,CAAC;YACrD,MAAM,QAAQ,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjF,IAAI,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACtC,IAAI,CAAC,gBAAgB,GAAG,QAAQ,CAAC;gBACjC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;YAChD,CAAC;YACD,MAAM,SAAS,GAAG,IAAA,mBAAU,GAAE,CAAC;YAC/B,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACvC,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;YAC1C,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;YAClC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,QAAQ,GAAG,IAAA,mBAAU,GAAE,CAAC;YAC9B,IAAI,CAAC,gBAAgB,GAAG,QAAQ,CAAC;YACjC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAC/C,CAAC;IACH,CAAC;IAED;;;;OAIG;IACK,YAAY,CAAC,KAA2B,EAAE,UAAkB;QAClE,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;QACxB,MAAM,OAAO,GACX,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;YACnC,CAAC,CAAC,YAAY;YACd,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,aAAa,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,SAAS;gBAC5E,CAAC,CAAC,aAAa;gBACf,CAAC,CAAC,OAAO,CAAC;QAEhB,IAAI,YAAY,GAAa,EAAE,CAAC;QAChC,IAAI,CAAC;YACH,YAAY,GAAG,IAAI,CAAC,UAAU,EAAE,aAAa,EAAE,CAAC,SAAS,IAAI,EAAE,CAAC;QAClE,CAAC;QAAC,MAAM,CAAC;YACP,iEAAiE;QACnE,CAAC;QACD,IAAI,eAAe,GAAa,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,eAAe,GAAG,IAAI,CAAC,sBAAsB,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;QACvE,CAAC;QAAC,MAAM,CAAC;YACP,iEAAiE;QACnE,CAAC;QAED,OAAO;YACL,aAAa,EAAE,CAAC;YAChB,UAAU;YACV,KAAK;YACL,WAAW,EAAE,IAAA,oCAAc,GAAE;YAC7B,SAAS,EAAE,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YAC5D,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO;YACP,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,MAAM,EAAE;gBACN,mBAAmB,EAAE,GAAG,CAAC,aAAa,EAAE,MAAM,IAAI,MAAM;gBACxD,GAAG,EAAE;oBACH,OAAO,EAAE,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI;oBAClC,WAAW,EAAE,GAAG,CAAC,GAAG,EAAE,WAAW,IAAI,IAAI;oBACzC,cAAc,EAAE,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,SAAS;oBAClD,cAAc,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,cAAc,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;iBACtE;gBACD,YAAY;gBACZ,eAAe;gBACf,cAAc,EAAE,IAAI,CAAC,kBAAkB,EAAE;gBACzC,wBAAwB,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,IAAI,IAAI;gBAChE,gBAAgB,EAAE,GAAG,CAAC,SAAS,EAAE,OAAO,KAAK,KAAK;gBAClD,gBAAgB,EAAE,GAAG,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI;gBACjD,qBAAqB,EAAE,GAAG,CAAC,WAAW,EAAE,OAAO,KAAK,SAAS;aAC9D;SACF,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACK,kBAAkB;QACxB,MAAM,OAAO,GAAG,IAAI,CAAC,cAA4E,CAAC;QAClG,OAAO,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,IAAI,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,IAAI,CAAC;IAClF,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,IAAI,CAAC,OAAyB;QAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,QAAQ,IAAI,gBAAgB,CAAC;QACrE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,eAAe,CAAC,CAAC;QACtE,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,QAAQ,EAAE;gBACpB,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;gBAC7B,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;YACrE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,oCAAoC,OAAO,EAAE,CAAC,CAAC;QACtE,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;CACF;AAvQD,4CAuQC"}

package/dist/utils/get-package-version.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Resolve the installed @nauth-toolkit/core version at runtime.
+ *
+ * Walks up from the compiled file location (dist/utils at runtime, src/utils
+ * under ts-jest) for up to three levels looking for the package's own
+ * package.json. Reading at runtime keeps the reported version in sync with
+ * the published package — a compiled-in constant would go stale because the
+ * release script bumps versions outside the TypeScript build.
+ *
+ * Never throws; returns 'unknown' when the manifest cannot be found or read.
+ *
+ * @returns The semver version string of @nauth-toolkit/core, or 'unknown'
+ */
+export declare function getCoreVersion(): string;
+//# sourceMappingURL=get-package-version.d.ts.map

package/dist/utils/get-package-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-package-version.d.ts","sourceRoot":"","sources":["../../src/utils/get-package-version.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,IAAI,MAAM,CA6BvC"}

package/dist/utils/get-package-version.js

@@ -0,0 +1,84 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCoreVersion = getCoreVersion;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Memoized result of the package.json version lookup.
+ * `undefined` means "not yet resolved"; a string (possibly 'unknown') is final.
+ */
+let cachedVersion;
+/**
+ * Resolve the installed @nauth-toolkit/core version at runtime.
+ *
+ * Walks up from the compiled file location (dist/utils at runtime, src/utils
+ * under ts-jest) for up to three levels looking for the package's own
+ * package.json. Reading at runtime keeps the reported version in sync with
+ * the published package — a compiled-in constant would go stale because the
+ * release script bumps versions outside the TypeScript build.
+ *
+ * Never throws; returns 'unknown' when the manifest cannot be found or read.
+ *
+ * @returns The semver version string of @nauth-toolkit/core, or 'unknown'
+ */
+function getCoreVersion() {
+    if (cachedVersion !== undefined) {
+        return cachedVersion;
+    }
+    let dir = __dirname;
+    for (let i = 0; i < 3; i++) {
+        dir = path.dirname(dir);
+        try {
+            const manifestPath = path.join(dir, 'package.json');
+            if (fs.existsSync(manifestPath)) {
+                const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+                if (typeof manifest === 'object' &&
+                    manifest !== null &&
+                    manifest.name === '@nauth-toolkit/core' &&
+                    typeof manifest.version === 'string') {
+                    cachedVersion = manifest.version;
+                    return cachedVersion;
+                }
+            }
+        }
+        catch {
+            // Unreadable or malformed manifest — keep walking up, fall through to 'unknown'.
+        }
+    }
+    cachedVersion = 'unknown';
+    return cachedVersion;
+}
+//# sourceMappingURL=get-package-version.js.map

package/dist/utils/get-package-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-package-version.js","sourceRoot":"","sources":["../../src/utils/get-package-version.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsBA,wCA6BC;AAnDD,uCAAyB;AACzB,2CAA6B;AAE7B;;;GAGG;AACH,IAAI,aAAiC,CAAC;AAEtC;;;;;;;;;;;;GAYG;AACH,SAAgB,cAAc;IAC5B,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,IAAI,GAAG,GAAG,SAAS,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;YACpD,IAAI,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;gBAChC,MAAM,QAAQ,GAAY,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;gBAC5E,IACE,OAAO,QAAQ,KAAK,QAAQ;oBAC5B,QAAQ,KAAK,IAAI;oBAChB,QAA+B,CAAC,IAAI,KAAK,qBAAqB;oBAC/D,OAAQ,QAAkC,CAAC,OAAO,KAAK,QAAQ,EAC/D,CAAC;oBACD,aAAa,GAAI,QAAgC,CAAC,OAAO,CAAC;oBAC1D,OAAO,aAAa,CAAC;gBACvB,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,iFAAiF;QACnF,CAAC;IACH,CAAC;IAED,aAAa,GAAG,SAAS,CAAC;IAC1B,OAAO,aAAa,CAAC;AACvB,CAAC"}

package/dist/utils/index.d.ts

@@ -3,6 +3,7 @@
  */
 export * from './pii-redactor';
 export * from './ip-extractor';
+export * from './ip-match';
 export * from './nauth-logger';
 export * from './cookies.util';
 export * from './cookie-names.util';

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC"}

package/dist/utils/index.js

@@ -19,6 +19,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./pii-redactor"), exports);
 __exportStar(require("./ip-extractor"), exports);
+__exportStar(require("./ip-match"), exports);
 __exportStar(require("./nauth-logger"), exports);
 __exportStar(require("./cookies.util"), exports);
 __exportStar(require("./cookie-names.util"), exports);

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;AAEH,iDAA+B;AAC/B,iDAA+B;AAC/B,iDAA+B;AAC/B,iDAA+B;AAC/B,sDAAoC;AACpC,oDAAkC;AAClC,0DAAwC;AACxC,uDAAqC;AACrC,kDAAgC;AAChC,wFAAwF"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;AAEH,iDAA+B;AAC/B,iDAA+B;AAC/B,6CAA2B;AAC3B,iDAA+B;AAC/B,iDAA+B;AAC/B,sDAAoC;AACpC,oDAAkC;AAClC,0DAAwC;AACxC,uDAAqC;AACrC,kDAAgC;AAChC,wFAAwF"}

package/dist/utils/ip-match.d.ts

@@ -0,0 +1,44 @@
+/**
+ * IP Allowlist Matching
+ *
+ * Utilities for matching a source IP against an allowlist entry that may be an
+ * exact IPv4/IPv6 address or an IPv4 CIDR range. Used to enforce per-API-key IP
+ * restrictions.
+ *
+ * @remarks
+ * IPv4 CIDR ranges (e.g. `10.0.0.0/8`) and exact IPv4/IPv6 addresses are supported.
+ * IPv6 CIDR ranges are not expanded; provide exact IPv6 addresses instead.
+ */
+/**
+ * Validate whether a string is a valid IP address or IPv4 CIDR range.
+ *
+ * @param entry - Candidate allowlist entry
+ * @returns true if the entry is a usable IP or IPv4 CIDR
+ *
+ * @example
+ * ```typescript
+ * isValidIpOrCidr('203.0.113.4');   // true
+ * isValidIpOrCidr('10.0.0.0/8');    // true
+ * isValidIpOrCidr('not-an-ip');     // false
+ * ```
+ */
+export declare function isValidIpOrCidr(entry: string): boolean;
+/**
+ * Determine whether a source IP matches a single allowlist entry.
+ *
+ * Supports:
+ * - Exact IPv4/IPv6 match (case-insensitive for IPv6)
+ * - IPv4 CIDR range match (e.g. `10.0.0.0/8`)
+ *
+ * @param ip - Source IP of the request
+ * @param entry - Allowlist entry (IP or IPv4 CIDR)
+ * @returns true if the IP is covered by the entry
+ *
+ * @example
+ * ```typescript
+ * ipMatchesEntry('10.1.2.3', '10.0.0.0/8'); // true
+ * ipMatchesEntry('203.0.113.4', '203.0.113.4'); // true
+ * ```
+ */
+export declare function ipMatchesEntry(ip: string, entry: string): boolean;
+//# sourceMappingURL=ip-match.d.ts.map

package/dist/utils/ip-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ip-match.d.ts","sourceRoot":"","sources":["../../src/utils/ip-match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAuCH;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAetD;AAkBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAwBjE"}