@zero-server/auth 0.9.1 → 0.9.3

package/lib/debug.js

@@ -0,0 +1,372 @@
+/**
+ * @module debug
+ * @description Lightweight namespaced debug logger with levels, colors, and timestamps.
+ *              Enable via DEBUG env variable: DEBUG=app:*,router (supports glob patterns).
+ *              Each namespace gets a unique color for easy visual scanning.
+ *
+ * Levels: trace (0), debug (1), info (2), warn (3), error (4), fatal (5), silent (6).
+ * Set level via DEBUG_LEVEL env var or programmatically.
+ *
+ * @example
+ *   const debug = require('@zero-server/sdk').debug;
+ *   const log = debug('app:routes');
+ *
+ *   log.info('server started on port %d', 3000);
+ *   log.warn('deprecation notice');
+ *   log.error('failed to connect', err);
+ *   log('shorthand for debug level');
+ *
+ *   // Set minimum level — anything below is silenced
+ *   debug.level('warn');   // only warn, error, fatal
+ *   debug.level('silent'); // suppress all output
+ *   debug.level('trace');  // show everything
+ *   debug.level(0);        // same as 'trace'
+ */
+
+const LEVELS = { trace: 0, debug: 1, info: 2, warn: 3, error: 4, fatal: 5, silent: 6 };
+const LEVEL_NAMES = ['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL'];
+const LEVEL_COLORS = ['\x1b[2m', '\x1b[36m', '\x1b[32m', '\x1b[33m', '\x1b[31m', '\x1b[35;1m'];
+
+// Namespace colors (rotate through these)
+const NS_COLORS = [
+    '\x1b[36m', '\x1b[33m', '\x1b[32m', '\x1b[35m', '\x1b[34m',
+    '\x1b[36;1m', '\x1b[33;1m', '\x1b[32;1m', '\x1b[35;1m', '\x1b[34;1m',
+];
+
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+
+let _colorIdx = 0;
+const _nsColorMap = new Map();
+
+/**
+ * Global state
+ */
+let _globalLevel = LEVELS[process.env.DEBUG_LEVEL] !== undefined
+    ? LEVELS[process.env.DEBUG_LEVEL]
+    : LEVELS.debug;
+
+let _enabledPatterns = null;
+let _output = process.stdout;
+let _outputCustom = false;
+let _useColors = process.stdout.isTTY || false;
+let _timestamps = true;
+let _jsonMode = false;
+
+/**
+ * Parse DEBUG env var into patterns.
+ * @private
+ */
+function _parsePatterns()
+{
+    const raw = process.env.DEBUG;
+    if (!raw) return null;
+    return raw.split(/[\s,]+/).filter(Boolean).map(p =>
+    {
+        const neg = p.startsWith('-');
+        const pat = neg ? p.slice(1) : p;
+        // Convert glob to regex: * => .*, ? => .
+        const re = new RegExp('^' + pat.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
+        return { neg, re };
+    });
+}
+
+_enabledPatterns = _parsePatterns();
+
+/**
+ * Check if a namespace is enabled.
+ * @private
+ * @param {string} ns - Debug namespace.
+ * @returns {boolean} True if the namespace matches the DEBUG patterns.
+ */
+function _isEnabled(ns)
+{
+    if (!_enabledPatterns) return true; // No DEBUG set — enable all
+    let enabled = false;
+    for (const { neg, re } of _enabledPatterns)
+    {
+        if (re.test(ns)) enabled = !neg;
+    }
+    return enabled;
+}
+
+/**
+ * Get a color for a namespace.
+ * @private
+ */
+function _nsColor(ns)
+{
+    if (!_nsColorMap.has(ns))
+    {
+        _nsColorMap.set(ns, NS_COLORS[_colorIdx % NS_COLORS.length]);
+        _colorIdx++;
+    }
+    return _nsColorMap.get(ns);
+}
+
+/**
+ * Format a timestamp.
+ * @private
+ */
+function _ts()
+{
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${String(d.getMilliseconds()).padStart(3, '0')}`;
+}
+
+/**
+ * Format arguments (like console.log — supports %s, %d, %j, %o).
+ * @private
+ */
+function _format(args)
+{
+    if (args.length === 0) return '';
+    if (typeof args[0] === 'string' && args.length > 1)
+    {
+        let i = 1;
+        const str = args[0].replace(/%([sdjo%])/g, (_, f) =>
+        {
+            if (f === '%') return '%';
+            if (i >= args.length) return `%${f}`;
+            const v = args[i++];
+            if (f === 's') return String(v);
+            if (f === 'd') return Number(v);
+            if (f === 'j' || f === 'o')
+            {
+                try { return JSON.stringify(v); }
+                catch { return String(v); }
+            }
+            return String(v);
+        });
+        const rest = args.slice(i).map(a =>
+            typeof a === 'object' ? JSON.stringify(a) : String(a)
+        );
+        return rest.length > 0 ? str + ' ' + rest.join(' ') : str;
+    }
+    return args.map(a =>
+    {
+        if (a instanceof Error) return a.stack || a.message;
+        if (typeof a === 'object')
+        {
+            try { return JSON.stringify(a); }
+            catch { return String(a); }
+        }
+        return String(a);
+    }).join(' ');
+}
+
+/**
+ * Write a log entry.
+ * @private
+ */
+function _write(ns, level, args)
+{
+    const msg = _format(args);
+    const out = (_outputCustom || level < LEVELS.warn) ? _output : process.stderr;
+
+    if (_jsonMode)
+    {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level: LEVEL_NAMES[level],
+            namespace: ns,
+            message: msg,
+        };
+        // If last arg is an Error, attach stack
+        const last = args[args.length - 1];
+        if (last instanceof Error)
+        {
+            entry.error = { message: last.message, stack: last.stack, code: last.code };
+        }
+        out.write(JSON.stringify(entry) + '\n');
+        return;
+    }
+
+    // Pretty text output
+    const parts = [];
+    if (_timestamps)
+    {
+        parts.push(_useColors ? `${DIM}${_ts()}${RESET}` : _ts());
+    }
+    // Level
+    const lvlName = LEVEL_NAMES[level];
+    if (_useColors)
+    {
+        parts.push(`${LEVEL_COLORS[level]}${lvlName.padEnd(5)}${RESET}`);
+    }
+    else
+    {
+        parts.push(lvlName.padEnd(5));
+    }
+    // Namespace
+    if (_useColors)
+    {
+        parts.push(`${_nsColor(ns)}${ns}${RESET}`);
+    }
+    else
+    {
+        parts.push(ns);
+    }
+    parts.push(msg);
+
+    out.write(parts.join(' ') + '\n');
+}
+
+/**
+ * Create a namespaced debug logger.
+ *
+ * @param {string} namespace - Logger namespace (e.g. 'app:routes', 'db:queries').
+ * @returns {Function & { trace, debug, info, warn, error, fatal, enabled }} Logger function.
+ */
+function debug(namespace)
+{
+    const enabled = _isEnabled(namespace);
+
+    // Default call = debug level
+    const logger = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.debug) return;
+        _write(namespace, LEVELS.debug, args);
+    };
+
+    logger.trace = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.trace) return;
+        _write(namespace, LEVELS.trace, args);
+    };
+
+    logger.debug = logger;
+
+    logger.info = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.info) return;
+        _write(namespace, LEVELS.info, args);
+    };
+
+    logger.warn = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.warn) return;
+        _write(namespace, LEVELS.warn, args);
+    };
+
+    logger.error = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.error) return;
+        _write(namespace, LEVELS.error, args);
+    };
+
+    logger.fatal = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.fatal) return;
+        _write(namespace, LEVELS.fatal, args);
+    };
+
+    /** Whether this namespace is active. */
+    logger.enabled = enabled;
+
+    /** The namespace string */
+    logger.namespace = namespace;
+
+    return logger;
+}
+
+// --- Configuration API -------------------------------------------
+
+/**
+ * Set the minimum log level globally.
+ * Messages below this level are silenced.
+ *
+ * @param {string|number} level - Level name or number.
+ *   `'trace'` (0) — all output
+ *   `'debug'` (1) — debug and above
+ *   `'info'` (2) — info and above
+ *   `'warn'` (3) — warn and above
+ *   `'error'` (4) — error and fatal only
+ *   `'fatal'` (5) — fatal only
+ *   `'silent'` (6) — nothing
+ */
+debug.level = function(level)
+{
+    if (typeof level === 'string') _globalLevel = LEVELS[level.toLowerCase()] ?? LEVELS.debug;
+    else _globalLevel = level;
+};
+
+/**
+ * Enable/disable namespaces programmatically (same syntax as DEBUG env var).
+ * @param {string} patterns - Comma-separated patterns. Use '-ns' to exclude.
+ */
+debug.enable = function(patterns)
+{
+    process.env.DEBUG = patterns;
+    _enabledPatterns = _parsePatterns();
+};
+
+/**
+ * Disable all debug output.
+ */
+debug.disable = function()
+{
+    process.env.DEBUG = '';
+    _enabledPatterns = [{ neg: false, re: /^$/ }]; // match nothing
+};
+
+/**
+ * Enable structured JSON output.
+ * @param {boolean} [on=true] - Enable flag.
+ */
+debug.json = function(on = true)
+{
+    _jsonMode = on;
+};
+
+/**
+ * Enable/disable timestamps.
+ * @param {boolean} [on=true] - Enable flag.
+ */
+debug.timestamps = function(on = true)
+{
+    _timestamps = on;
+};
+
+/**
+ * Enable/disable colors.
+ * @param {boolean} [on=true] - Enable flag.
+ */
+debug.colors = function(on = true)
+{
+    _useColors = on;
+};
+
+/**
+ * Set custom output stream.
+ * @param {object} stream - Writable stream with write() method.
+ */
+debug.output = function(stream)
+{
+    _output = stream;
+    _outputCustom = true;
+};
+
+/**
+ * Reset all settings to defaults.
+ */
+debug.reset = function()
+{
+    _globalLevel = LEVELS[process.env.DEBUG_LEVEL] !== undefined
+        ? LEVELS[process.env.DEBUG_LEVEL]
+        : LEVELS.debug;
+    _enabledPatterns = _parsePatterns();
+    _output = process.stdout;
+    _outputCustom = false;
+    _useColors = process.stdout.isTTY || false;
+    _timestamps = true;
+    _jsonMode = false;
+    _colorIdx = 0;
+    _nsColorMap.clear();
+};
+
+/** Expose level constants. */
+debug.LEVELS = LEVELS;
+
+module.exports = debug;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zero-server/auth",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "JWT, sessions, OAuth, authorize, MFA stack.",
   "keywords": [
     "zero-server",
@@ -20,6 +20,8 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "lib",
+    "types",
     "index.js",
     "index.d.ts",
     "README.md",
@@ -43,6 +45,14 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@zero-server/sdk": "0.9.1"
+    "@zero-server/fetch": "0.9.3"
+  },
+  "peerDependencies": {
+    "@zero-server/sdk": ">=0.9.3"
+  },
+  "peerDependenciesMeta": {
+    "@zero-server/sdk": {
+      "optional": true
+    }
   }
 }

package/types/app.d.ts

@@ -0,0 +1,223 @@
+/// <reference types="node" />
+
+import { Server as HttpServer } from 'http';
+import { Server as HttpsServer, ServerOptions as TlsOptions } from 'https';
+import { Http2Server, Http2SecureServer } from 'http2';
+import { Request } from './request';
+import { Response } from './response';
+import { RouterInstance, RouteChain, RouteInfo, RouteOptions, RouteHandler } from './router';
+import { MiddlewareFunction, ErrorHandlerFunction, NextFunction } from './middleware';
+import { WebSocketHandler, WebSocketOptions, WebSocketPool } from './websocket';
+import { SSEStream } from './sse';
+import { LifecycleState } from './lifecycle';
+import { MetricsRegistry, HealthCheckResult } from './observe';
+import { ProtoSchema, GrpcServiceOptions, GrpcInterceptor, GrpcHandler } from './grpc';
+
+export interface ListenOptions {
+    /** Create an HTTP/2 server. Combined with TLS options for h2 over TLS, or h2c (cleartext) otherwise. */
+    http2?: boolean;
+    /** Allow HTTP/1.1 fallback on HTTP/2 TLS servers (ALPN negotiation). Default: true. */
+    allowHTTP1?: boolean;
+}
+
+export interface App {
+    /** Internal router instance. */
+    router: RouterInstance;
+    /** Middleware stack. */
+    middlewares: MiddlewareFunction[];
+    /** Application-level locals, merged into every request/response locals. */
+    locals: Record<string, any>;
+
+    /**
+     * Register middleware or mount a sub-router.
+     */
+    use(fn: MiddlewareFunction): App;
+    use(path: string, fn: MiddlewareFunction): App;
+    use(path: string, router: RouterInstance): App;
+
+    /**
+     * Register a global error handler.
+     */
+    onError(fn: ErrorHandlerFunction): void;
+
+    /**
+     * Core request handler for use with `http.createServer()`.
+     */
+    handler(req: import('http').IncomingMessage, res: import('http').ServerResponse): void;
+
+    /**
+     * Start listening for connections.
+     * Pass `{ http2: true }` to create an HTTP/2 server (h2c cleartext or TLS with ALPN).
+     */
+    listen(port?: number, cb?: () => void): HttpServer;
+    listen(port: number, opts: TlsOptions, cb?: () => void): HttpsServer;
+    listen(port: number, opts: ListenOptions & { http2: true } & TlsOptions, cb?: () => void): Http2SecureServer;
+    listen(port: number, opts: ListenOptions & { http2: true }, cb?: () => void): Http2Server;
+    listen(port: number, opts: ListenOptions, cb?: () => void): HttpServer | HttpsServer | Http2Server | Http2SecureServer;
+
+    /**
+     * Gracefully close the server.
+     */
+    close(cb?: (err?: Error) => void): void;
+
+    /**
+     * Perform a full graceful shutdown.
+     */
+    shutdown(opts?: { timeout?: number }): Promise<void>;
+
+    /**
+     * Register a lifecycle event listener.
+     */
+    on(event: 'beforeShutdown' | 'shutdown', fn: () => void | Promise<void>): App;
+
+    /**
+     * Remove a lifecycle event listener.
+     */
+    off(event: 'beforeShutdown' | 'shutdown', fn: () => void | Promise<void>): App;
+
+    /**
+     * Register a WebSocket pool for graceful shutdown.
+     */
+    registerPool(pool: WebSocketPool): App;
+
+    /**
+     * Unregister a WebSocket pool from lifecycle management.
+     */
+    unregisterPool(pool: WebSocketPool): App;
+
+    /**
+     * Track an SSE stream for graceful shutdown.
+     */
+    trackSSE(stream: SSEStream): App;
+
+    /**
+     * Register an ORM Database for graceful shutdown.
+     */
+    registerDatabase(db: { close(): Promise<void> }): App;
+
+    /**
+     * Unregister an ORM Database from lifecycle management.
+     */
+    unregisterDatabase(db: { close(): Promise<void> }): App;
+
+    /**
+     * Configure the shutdown timeout in milliseconds.
+     */
+    shutdownTimeout(ms: number): App;
+
+    /**
+     * Current lifecycle state.
+     */
+    readonly lifecycleState: LifecycleState;
+
+    /**
+     * Register a liveness health check endpoint.
+     */
+    health(path?: string, checks?: Record<string, () => HealthCheckResult | boolean | Promise<HealthCheckResult | boolean>>): App;
+    health(checks?: Record<string, () => HealthCheckResult | boolean | Promise<HealthCheckResult | boolean>>): App;
+
+    /**
+     * Register a readiness health check endpoint.
+     */
+    ready(path?: string, checks?: Record<string, () => HealthCheckResult | boolean | Promise<HealthCheckResult | boolean>>): App;
+    ready(checks?: Record<string, () => HealthCheckResult | boolean | Promise<HealthCheckResult | boolean>>): App;
+
+    /**
+     * Register a custom health check.
+     */
+    addHealthCheck(name: string, fn: () => HealthCheckResult | boolean | Promise<HealthCheckResult | boolean>): App;
+
+    /**
+     * Get the application metrics registry.
+     */
+    metrics(): MetricsRegistry;
+
+    /**
+     * Mount a Prometheus metrics endpoint.
+     */
+    metricsEndpoint(path?: string, opts?: { registry?: MetricsRegistry }): App;
+
+    /**
+     * Register a WebSocket upgrade handler.
+     */
+    ws(path: string, handler: WebSocketHandler): void;
+    ws(path: string, opts: WebSocketOptions, handler: WebSocketHandler): void;
+
+    /**
+     * Register a gRPC service with handlers.
+     */
+    grpc(schema: ProtoSchema, serviceName: string, handlers: Record<string, GrpcHandler>, opts?: GrpcServiceOptions): App;
+
+    /**
+     * Add a global gRPC interceptor.
+     */
+    grpcInterceptor(fn: GrpcInterceptor): App;
+
+    /**
+     * Return a flat list of all registered routes.
+     */
+    routes(): RouteInfo[];
+
+    /**
+     * Register a route with a specific HTTP method.
+     */
+    route(method: string, path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+
+    /**
+     * Get a setting value (1 arg) or set a setting value (2 args).
+     */
+    set(key: string): any;
+    set(key: string, val: any): App;
+
+    /**
+     * Get a setting value, or register a GET route.
+     * With 1 string arg: returns the setting value.
+     * With path + handlers: registers a GET route.
+     */
+    get(key: string): any;
+    get(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+
+    /**
+     * Enable a boolean setting (set to `true`).
+     */
+    enable(key: string): App;
+
+    /**
+     * Disable a boolean setting (set to `false`).
+     */
+    disable(key: string): App;
+
+    /**
+     * Check if a setting is truthy.
+     */
+    enabled(key: string): boolean;
+
+    /**
+     * Check if a setting is falsy.
+     */
+    disabled(key: string): boolean;
+
+    /**
+     * Register a parameter pre-processing handler.
+     */
+    param(name: string, fn: (req: Request, res: Response, next: NextFunction, value: string) => void): App;
+
+    /**
+     * Create a route group under a prefix with shared middleware.
+     */
+    group(prefix: string, ...args: [...MiddlewareFunction[], (router: RouterInstance) => void]): App;
+
+    /**
+     * Create a chainable route builder for the given path.
+     */
+    chain(path: string): RouteChain;
+
+    // HTTP method shortcuts
+    post(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    put(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    delete(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    patch(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    options(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    head(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    all(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+}