reqon-dsl 0.2.0 → 0.4.0

package/dist/utils/path.d.ts

@@ -7,6 +7,27 @@
  */
 export declare function extractNestedValue(data: Record<string, unknown>, path: string): unknown;
 /**
- * Traverse an object path and return the value, with fallback lookup
+ * Error thrown when a path segment would escape its base directory.
  */
+export declare class PathTraversalError extends Error {
+    readonly segment: string;
+    readonly baseDir: string;
+    constructor(segment: string, baseDir: string);
+}
+/**
+ * Safely join an untrusted path segment under a base directory, asserting the
+ * result stays confined inside that base. Guards against `../`, absolute paths,
+ * and embedded separators in store names / IDs.
+ *
+ * @throws {PathTraversalError} if the resolved path escapes baseDir
+ */
+export declare function safeJoin(baseDir: string, ...segments: string[]): string;
+/**
+ * Sanitize a single untrusted path segment (e.g. a store name or record ID) so
+ * it cannot traverse directories. Rejects empty, separator-bearing, or
+ * traversal segments rather than silently mangling them.
+ *
+ * @throws {PathTraversalError} if the segment is unsafe
+ */
+export declare function sanitizeSegment(segment: string, baseDir?: string): string;
 export declare function traversePath(parts: string[], current: unknown, fallbackLookup?: (key: string) => unknown): unknown;

package/dist/utils/path.js

@@ -1,6 +1,7 @@
 /**
  * Utility functions for path traversal and value extraction
  */
+import { join, resolve, sep } from 'node:path';
 /**
  * Extract a nested value from an object using dot notation path
  * @example extractNestedValue({ a: { b: 1 } }, 'a.b') // => 1
@@ -19,8 +20,52 @@ export function extractNestedValue(data, path) {
     return value;
 }
 /**
- * Traverse an object path and return the value, with fallback lookup
+ * Error thrown when a path segment would escape its base directory.
  */
+export class PathTraversalError extends Error {
+    segment;
+    baseDir;
+    constructor(segment, baseDir) {
+        super(`Path segment "${segment}" escapes base directory "${baseDir}"`);
+        this.segment = segment;
+        this.baseDir = baseDir;
+        this.name = 'PathTraversalError';
+    }
+}
+/**
+ * Safely join an untrusted path segment under a base directory, asserting the
+ * result stays confined inside that base. Guards against `../`, absolute paths,
+ * and embedded separators in store names / IDs.
+ *
+ * @throws {PathTraversalError} if the resolved path escapes baseDir
+ */
+export function safeJoin(baseDir, ...segments) {
+    const base = resolve(baseDir);
+    const joined = resolve(base, ...segments);
+    // Confined if it equals the base or sits inside it (base + separator prefix).
+    if (joined !== base && !joined.startsWith(base + sep)) {
+        throw new PathTraversalError(join(...segments), baseDir);
+    }
+    return joined;
+}
+/**
+ * Sanitize a single untrusted path segment (e.g. a store name or record ID) so
+ * it cannot traverse directories. Rejects empty, separator-bearing, or
+ * traversal segments rather than silently mangling them.
+ *
+ * @throws {PathTraversalError} if the segment is unsafe
+ */
+export function sanitizeSegment(segment, baseDir = '.') {
+    if (segment.length === 0 ||
+        segment === '.' ||
+        segment === '..' ||
+        segment.includes('/') ||
+        segment.includes('\\') ||
+        segment.includes('\0')) {
+        throw new PathTraversalError(segment, baseDir);
+    }
+    return segment;
+}
 export function traversePath(parts, current, fallbackLookup) {
     let value = current;
     for (let i = 0; i < parts.length; i++) {

package/dist/utils/redact.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Secret redaction for logs, error messages, and durable trace files.
+ *
+ * Uses a denylist of sensitive key-name patterns: any object property whose
+ * key looks like a credential is replaced with {@link REDACTED}. This is a
+ * best-effort guard — it cannot catch a raw secret stored under an innocuous
+ * key — so callers should also avoid persisting cleartext credentials.
+ */
+export declare const REDACTED = "[REDACTED]";
+/** True when a key name looks like it holds a credential. */
+export declare function isSensitiveKey(key: string): boolean;
+/**
+ * Return a deep copy of `value` with any credential-looking properties
+ * replaced by {@link REDACTED}. Non-objects are returned unchanged. Cycles are
+ * handled, and the input is never mutated.
+ */
+export declare function redactSecrets<T>(value: T, seen?: WeakSet<object>): T;
+/**
+ * Redact a named value for logging: if the name itself looks sensitive the
+ * whole value is hidden; otherwise nested credential properties are redacted.
+ */
+export declare function redactNamedValue(name: string, value: unknown): unknown;

package/dist/utils/redact.js

@@ -0,0 +1,42 @@
+/**
+ * Secret redaction for logs, error messages, and durable trace files.
+ *
+ * Uses a denylist of sensitive key-name patterns: any object property whose
+ * key looks like a credential is replaced with {@link REDACTED}. This is a
+ * best-effort guard — it cannot catch a raw secret stored under an innocuous
+ * key — so callers should also avoid persisting cleartext credentials.
+ */
+export const REDACTED = '[REDACTED]';
+/** Key names that should never have their value logged or persisted in clear. */
+const SENSITIVE_KEY = /(pass(word|wd)?|secret|token|auth(orization)?|api[-_]?key|access[-_]?key|client[-_]?secret|credential|cookie|session|bearer|private[-_]?key)/i;
+/** True when a key name looks like it holds a credential. */
+export function isSensitiveKey(key) {
+    return SENSITIVE_KEY.test(key);
+}
+/**
+ * Return a deep copy of `value` with any credential-looking properties
+ * replaced by {@link REDACTED}. Non-objects are returned unchanged. Cycles are
+ * handled, and the input is never mutated.
+ */
+export function redactSecrets(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (seen.has(value))
+        return value;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => redactSecrets(item, seen));
+    }
+    const out = {};
+    for (const [key, val] of Object.entries(value)) {
+        out[key] = isSensitiveKey(key) ? REDACTED : redactSecrets(val, seen);
+    }
+    return out;
+}
+/**
+ * Redact a named value for logging: if the name itself looks sensitive the
+ * whole value is hidden; otherwise nested credential properties are redacted.
+ */
+export function redactNamedValue(name, value) {
+    return isSensitiveKey(name) ? REDACTED : redactSecrets(value);
+}

package/dist/utils/type-guards.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Type guard utilities to reduce type assertions and improve type safety.
+ * These guards provide runtime type checking with TypeScript type narrowing.
+ */
+/**
+ * Type guard to check if a value is a non-null object (excluding arrays).
+ * Narrows the type to Record<string, unknown> for safe property access.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Type guard to check if a value is a non-null object (including arrays).
+ * Useful when you need to access properties on any object-like value.
+ */
+export declare function isObject(value: unknown): value is object;
+/**
+ * Type guard to check if a value is an array of a specific type.
+ * Performs runtime check on each element using the provided guard.
+ */
+export declare function isArrayOf<T>(value: unknown, guard: (item: unknown) => item is T): value is T[];
+/**
+ * Type guard to check if a value is a string.
+ */
+export declare function isString(value: unknown): value is string;
+/**
+ * Type guard to check if a value is a number.
+ */
+export declare function isNumber(value: unknown): value is number;
+/**
+ * Type guard to check if a value is a boolean.
+ */
+export declare function isBoolean(value: unknown): value is boolean;
+/**
+ * Type guard to check if a value is defined (not undefined).
+ */
+export declare function isDefined<T>(value: T | undefined): value is T;
+/**
+ * Type guard to check if a value is not null or undefined.
+ */
+export declare function isPresent<T>(value: T | null | undefined): value is T;
+/**
+ * Safely access a property on an unknown value.
+ * Returns undefined if the value is not an object or the property doesn't exist.
+ */
+export declare function getProperty(value: unknown, key: string): unknown;
+/**
+ * Safely access a nested property path on an unknown value.
+ * Returns undefined if any part of the path is not an object.
+ */
+export declare function getNestedProperty(value: unknown, path: string[]): unknown;
+/**
+ * Check if an object has a specific property.
+ * Narrows the type to include that property.
+ */
+export declare function hasProperty<K extends string>(value: unknown, key: K): value is Record<K, unknown>;
+/**
+ * Check if an object has a specific property with a specific type.
+ */
+export declare function hasTypedProperty<K extends string, T>(value: unknown, key: K, guard: (v: unknown) => v is T): value is Record<K, T>;

package/dist/utils/type-guards.js

@@ -0,0 +1,92 @@
+/**
+ * Type guard utilities to reduce type assertions and improve type safety.
+ * These guards provide runtime type checking with TypeScript type narrowing.
+ */
+/**
+ * Type guard to check if a value is a non-null object (excluding arrays).
+ * Narrows the type to Record<string, unknown> for safe property access.
+ */
+export function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Type guard to check if a value is a non-null object (including arrays).
+ * Useful when you need to access properties on any object-like value.
+ */
+export function isObject(value) {
+    return value !== null && typeof value === 'object';
+}
+/**
+ * Type guard to check if a value is an array of a specific type.
+ * Performs runtime check on each element using the provided guard.
+ */
+export function isArrayOf(value, guard) {
+    return Array.isArray(value) && value.every(guard);
+}
+/**
+ * Type guard to check if a value is a string.
+ */
+export function isString(value) {
+    return typeof value === 'string';
+}
+/**
+ * Type guard to check if a value is a number.
+ */
+export function isNumber(value) {
+    return typeof value === 'number';
+}
+/**
+ * Type guard to check if a value is a boolean.
+ */
+export function isBoolean(value) {
+    return typeof value === 'boolean';
+}
+/**
+ * Type guard to check if a value is defined (not undefined).
+ */
+export function isDefined(value) {
+    return value !== undefined;
+}
+/**
+ * Type guard to check if a value is not null or undefined.
+ */
+export function isPresent(value) {
+    return value !== null && value !== undefined;
+}
+/**
+ * Safely access a property on an unknown value.
+ * Returns undefined if the value is not an object or the property doesn't exist.
+ */
+export function getProperty(value, key) {
+    if (isRecord(value)) {
+        return value[key];
+    }
+    return undefined;
+}
+/**
+ * Safely access a nested property path on an unknown value.
+ * Returns undefined if any part of the path is not an object.
+ */
+export function getNestedProperty(value, path) {
+    let current = value;
+    for (const key of path) {
+        if (!isRecord(current)) {
+            return undefined;
+        }
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * Check if an object has a specific property.
+ * Narrows the type to include that property.
+ */
+export function hasProperty(value, key) {
+    return isRecord(value) && key in value;
+}
+/**
+ * Check if an object has a specific property with a specific type.
+ */
+export function hasTypedProperty(value, key, guard) {
+    return hasProperty(value, key) && guard(value[key]);
+}

package/dist/webhook/server.d.ts

@@ -45,6 +45,8 @@ export declare class WebhookServer {
      * Wait for webhook events
      */
     waitForEvents(registrationId: string, timeout?: number): Promise<WaitResult>;
+    /** Remove a single waiter, dropping the registration's set when empty. */
+    private removePendingWait;
     /**
      * Unregister a webhook endpoint
      */
@@ -69,6 +71,13 @@ export declare class WebhookServer {
      * Read request body
      */
     private readBody;
+    /** True if a host string is a loopback address. */
+    private isLoopback;
+    /**
+     * Validate the shared secret from Authorization bearer, X-Webhook-Token
+     * header, or a `token` query param.
+     */
+    private authorized;
     /**
      * Extract headers from request
      */

package/dist/webhook/server.js

@@ -7,7 +7,9 @@
 import { createServer } from 'node:http';
 import { parse as parseUrl } from 'node:url';
 import { randomUUID } from 'node:crypto';
+import { setLongTimeout } from '../utils/long-timeout.js';
 import { MemoryWebhookStore } from './store.js';
+import { WEBHOOK_DEFAULTS } from '../config/index.js';
 /**
  * Webhook Server
  *
@@ -18,16 +20,20 @@ export class WebhookServer {
     store;
     callbacks;
     server;
+    // Multiple concurrent waiters may await the same registration; each gets its
+    // own entry so a second waiter can't clobber the first's timer/promise.
     pendingWaits = new Map();
     cleanupInterval;
     running = false;
     constructor(config = {}, store, callbacks = {}) {
         this.config = {
-            port: config.port ?? 3000,
-            host: config.host ?? '0.0.0.0',
-            baseUrl: config.baseUrl ?? `http://localhost:${config.port ?? 3000}`,
-            defaultTimeout: config.defaultTimeout ?? 300000, // 5 minutes
+            port: config.port ?? WEBHOOK_DEFAULTS.PORT,
+            host: config.host ?? WEBHOOK_DEFAULTS.HOST,
+            baseUrl: config.baseUrl ?? `http://localhost:${config.port ?? WEBHOOK_DEFAULTS.PORT}`,
+            defaultTimeout: config.defaultTimeout ?? WEBHOOK_DEFAULTS.DEFAULT_TIMEOUT_MS,
             verbose: config.verbose ?? false,
+            secret: config.secret ?? '',
+            maxBodyBytes: config.maxBodyBytes ?? WEBHOOK_DEFAULTS.MAX_BODY_BYTES,
         };
         this.store = store ?? new MemoryWebhookStore();
         this.callbacks = callbacks;
@@ -38,16 +44,22 @@ export class WebhookServer {
     async start() {
         if (this.running)
             return;
+        // Warn loudly if exposing an unauthenticated webhook server off-host.
+        if (!this.isLoopback(this.config.host) && !this.config.secret) {
+            console.warn(`[Webhook] WARNING: binding to ${this.config.host} with no secret — ` +
+                `anyone who can reach the port can inject events.`);
+        }
         return new Promise((resolve, reject) => {
             this.server = createServer((req, res) => this.handleRequest(req, res));
+            this.server.setTimeout(WEBHOOK_DEFAULTS.SOCKET_TIMEOUT_MS);
             this.server.on('error', (error) => {
                 reject(error);
             });
             this.server.listen(this.config.port, this.config.host, () => {
                 this.running = true;
                 this.log(`Webhook server listening on ${this.config.host}:${this.config.port}`);
-                // Start cleanup interval (every minute)
-                this.cleanupInterval = setInterval(() => this.cleanup(), 60000);
+                // Start cleanup interval
+                this.cleanupInterval = setInterval(() => this.cleanup(), WEBHOOK_DEFAULTS.CLEANUP_INTERVAL_MS);
                 resolve();
             });
         });
@@ -64,13 +76,15 @@ export class WebhookServer {
             this.cleanupInterval = undefined;
         }
         // Cancel all pending waits
-        for (const [id, pending] of this.pendingWaits) {
-            clearTimeout(pending.timeoutId);
-            pending.resolve({
-                success: false,
-                events: [],
-                error: 'Server shutting down',
-            });
+        for (const [, waiters] of this.pendingWaits) {
+            for (const pending of waiters) {
+                pending.timer.clear();
+                pending.resolve({
+                    success: false,
+                    events: [],
+                    error: 'Server shutting down',
+                });
+            }
         }
         this.pendingWaits.clear();
         // Close server
@@ -133,10 +147,11 @@ export class WebhookServer {
             return { success: true, events };
         }
         // Wait for more events
-        const waitTimeout = timeout ?? (registration.expiresAt.getTime() - Date.now());
+        const waitTimeout = timeout ?? registration.expiresAt.getTime() - Date.now();
         return new Promise((resolve) => {
-            const timeoutId = setTimeout(() => {
-                this.pendingWaits.delete(registrationId);
+            const pending = { registrationId, resolve, timer: undefined };
+            pending.timer = setLongTimeout(() => {
+                this.removePendingWait(registrationId, pending);
                 this.store.getEvents(registrationId).then((events) => {
                     resolve({
                         success: events.length >= registration.expectedEvents,
@@ -145,23 +160,36 @@ export class WebhookServer {
                     });
                 });
             }, waitTimeout);
-            this.pendingWaits.set(registrationId, {
-                registrationId,
-                resolve,
-                timeoutId,
-            });
+            let waiters = this.pendingWaits.get(registrationId);
+            if (!waiters) {
+                waiters = new Set();
+                this.pendingWaits.set(registrationId, waiters);
+            }
+            waiters.add(pending);
         });
     }
+    /** Remove a single waiter, dropping the registration's set when empty. */
+    removePendingWait(registrationId, pending) {
+        const waiters = this.pendingWaits.get(registrationId);
+        if (!waiters)
+            return;
+        waiters.delete(pending);
+        if (waiters.size === 0) {
+            this.pendingWaits.delete(registrationId);
+        }
+    }
     /**
      * Unregister a webhook endpoint
      */
     async unregister(registrationId) {
         await this.store.deleteRegistration(registrationId);
         await this.store.deleteEvents(registrationId);
-        // Cancel pending wait if any
-        const pending = this.pendingWaits.get(registrationId);
-        if (pending) {
-            clearTimeout(pending.timeoutId);
+        // Cancel any pending waits for this registration.
+        const waiters = this.pendingWaits.get(registrationId);
+        if (waiters) {
+            for (const pending of waiters) {
+                pending.timer.clear();
+            }
             this.pendingWaits.delete(registrationId);
         }
         this.log(`Unregistered webhook: ${registrationId}`);
@@ -210,11 +238,31 @@ export class WebhookServer {
             await this.store.deleteRegistration(registration.id);
             return;
         }
-        // Parse request body
+        // Require the shared secret if one is configured.
+        if (this.config.secret && !this.authorized(req, url.query)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Unauthorized' }));
+            return;
+        }
+        // Read the request body with a hard size cap to prevent an OOM from a
+        // large or slow-drip POST.
         let rawBody = '';
-        let body = null;
         try {
             rawBody = await this.readBody(req);
+        }
+        catch (error) {
+            if (error.code === 'BODY_TOO_LARGE') {
+                res.writeHead(413, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Request body too large' }));
+                return;
+            }
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Failed to read request body' }));
+            return;
+        }
+        // Parse request body
+        let body = null;
+        try {
             if (rawBody) {
                 const contentType = req.headers['content-type'] ?? '';
                 if (contentType.includes('application/json')) {
@@ -228,7 +276,7 @@ export class WebhookServer {
                 }
             }
         }
-        catch (error) {
+        catch {
             body = rawBody;
         }
         // Create event
@@ -252,12 +300,14 @@ export class WebhookServer {
         if (registration.receivedEvents >= registration.expectedEvents) {
             const events = await this.store.getEvents(registration.id);
             this.callbacks.onRegistrationComplete?.(registration, events);
-            // Resolve pending wait
-            const pending = this.pendingWaits.get(registration.id);
-            if (pending) {
-                clearTimeout(pending.timeoutId);
+            // Resolve every pending waiter for this registration.
+            const waiters = this.pendingWaits.get(registration.id);
+            if (waiters) {
                 this.pendingWaits.delete(registration.id);
-                pending.resolve({ success: true, events });
+                for (const pending of waiters) {
+                    pending.timer.clear();
+                    pending.resolve({ success: true, events });
+                }
             }
         }
         // Send response
@@ -273,17 +323,53 @@ export class WebhookServer {
      * Read request body
      */
     readBody(req) {
+        const limit = this.config.maxBodyBytes;
         return new Promise((resolve, reject) => {
-            let data = '';
+            const chunks = [];
+            let size = 0;
+            let aborted = false;
             req.on('data', (chunk) => {
-                data += chunk;
+                if (aborted)
+                    return;
+                size += chunk.length;
+                if (size > limit) {
+                    // Stop accumulating (memory stays bounded) and reject; the handler
+                    // responds 413. We don't destroy the socket here so the response
+                    // can flush first.
+                    aborted = true;
+                    const err = new Error('Request body too large');
+                    err.code = 'BODY_TOO_LARGE';
+                    reject(err);
+                    return;
+                }
+                chunks.push(chunk);
             });
             req.on('end', () => {
-                resolve(data);
+                resolve(Buffer.concat(chunks).toString('utf-8'));
             });
             req.on('error', reject);
         });
     }
+    /** True if a host string is a loopback address. */
+    isLoopback(host) {
+        return host === 'localhost' || host === '127.0.0.1' || host === '::1';
+    }
+    /**
+     * Validate the shared secret from Authorization bearer, X-Webhook-Token
+     * header, or a `token` query param.
+     */
+    authorized(req, query) {
+        const secret = this.config.secret;
+        const auth = req.headers.authorization;
+        if (auth === `Bearer ${secret}`)
+            return true;
+        const tokenHeader = req.headers['x-webhook-token'];
+        if (tokenHeader === secret)
+            return true;
+        if (typeof query.token === 'string' && query.token === secret)
+            return true;
+        return false;
+    }
     /**
      * Extract headers from request
      */

package/dist/webhook/types.d.ts

@@ -51,7 +51,7 @@ export interface WebhookEvent {
 export interface WebhookServerConfig {
     /** Port to listen on (default: 3000) */
     port?: number;
-    /** Host to bind to (default: '0.0.0.0') */
+    /** Host to bind to (default: '127.0.0.1' — loopback only) */
     host?: string;
     /** Base URL for webhook endpoints (e.g., 'https://example.com/webhooks') */
     baseUrl?: string;
@@ -59,6 +59,14 @@ export interface WebhookServerConfig {
     defaultTimeout?: number;
     /** Enable verbose logging */
     verbose?: boolean;
+    /**
+     * Shared secret required on inbound webhook requests. When set, a request
+     * must present it via `Authorization: Bearer <secret>`, `X-Webhook-Token`,
+     * or a `token` query param, or it is rejected with 401.
+     */
+    secret?: string;
+    /** Maximum accepted request body size in bytes (default 1 MiB) */
+    maxBodyBytes?: number;
 }
 /**
  * Callbacks for webhook server events