guardian-risk-logger 0.1.1 → 0.2.0

package/README.md

@@ -6,9 +6,7 @@
 npm install guardian-risk guardian-risk-logger
 ```
 
-> **Stub package** — API may change before `1.0.0`.
-
-Audit logging for [guardian-risk](https://www.npmjs.com/package/guardian-risk). Records risk reports, matched rules, and scores for compliance and debugging.
+Audit logging for [guardian-risk](https://www.npmjs.com/package/guardian-risk) analysis results.
 
 ## What gets logged
 
@@ -16,43 +14,34 @@ Audit logging for [guardian-risk](https://www.npmjs.com/package/guardian-risk).
 |-------|--------|
 | `score` | `report.score` |
 | `riskLevel` | `report.level` |
-| `matchedRules` | Count and details from `report.matchedRules` |
+| `matchedRules` | Rule names from `report.matchedRules` |
 | `reasons` | `report.reasons` |
-| `analyzedAt` | `report.analyzedAt` |
+| `context` | Sanitized request metadata (method, path, IP only) |
 
-## Usage (stub)
+## Production usage
 
 ```typescript
 import { Guardian } from 'guardian-risk';
-import { loggerPlugin, analyzeAndLog } from 'guardian-risk-logger';
-import { vpnPlugin } from 'guardian-risk-vpn';
+import { loggerPlugin } from 'guardian-risk-logger';
 
-const guardian = new Guardian()
+const template = new Guardian()
   .use(loggerPlugin({ level: 'info', minScore: 20 }))
-  .use(vpnPlugin());
-
-guardian.signal('vpn', true);
+  .rule({ name: 'Bot', when: (s) => s.headlessUA === true, score: 30 });
 
-const report = analyzeAndLog(guardian, { minScore: 0 });
+// Middleware runs analyzeAsync → afterAnalyze logs automatically
 ```
 
-## Custom sink
+## Security notes
 
-```typescript
-import { loggerPlugin, logReport, type LogSink } from 'guardian-risk-logger';
-
-const sink: LogSink = {
-  write(entry) {
-    // Send to Datadog, CloudWatch, file, etc.
-    myAuditService.record(entry);
-  },
-};
-
-const guardian = new Guardian().use(loggerPlugin({ sink }));
-const report = guardian.analyze();
-logReport(report, { sink });
-```
+- Request **headers are redacted** from log context — only method, path, and validated IP are kept.
+- Do not log raw cookies, auth tokens, or PII in custom sinks.
+- Use `minScore` to reduce noise in high-traffic apps.
+
+## API
 
-## Status
+- `loggerPlugin(options)` — `afterAnalyze` auto-logging
+- `analyzeAndLog(guardian, options)` — one-shot analyze + log
+- `logReport(report, options)` — log an existing report
+- `LogSink` — custom destination (Datadog, CloudWatch, etc.)
 
-Not yet published. Implementation in progress.
+See [SECURITY.md](../../SECURITY.md).

package/dist/index.cjs

@@ -15,37 +15,74 @@ var defaultSink = {
       score: entry.report.score,
       riskLevel: entry.report.level,
       matchedRules: entry.report.matchedRules.length,
-      timestamp: entry.timestamp
+      timestamp: entry.timestamp,
+      ...entry.context !== void 0 ? { context: entry.context } : {}
     });
     console.log(`[guardian-risk] ${payload}`);
   }
 };
 function loggerPlugin(options = {}) {
-  const { level = "info", sink = defaultSink, minScore = 0 } = options;
+  const resolved = {
+    level: "info",
+    sink: defaultSink,
+    minScore: 0,
+    includeContext: true,
+    ...options
+  };
   return {
     name: "guardian-risk-logger",
-    install(_guardian) {
+    install(guardian) {
+      guardian.afterAnalyze(({ report, data }) => {
+        logReport(report, {
+          ...resolved,
+          context: resolved.includeContext ? sanitizeLogContext(data) : void 0
+        });
+      });
     }
   };
 }
 function logReport(report, options = {}) {
-  const { level = "info", sink = defaultSink, minScore = 0 } = options;
+  const {
+    level = "info",
+    sink = defaultSink,
+    minScore = 0,
+    context,
+    includeContext = true
+  } = options;
   if (report.score < minScore) {
     return;
   }
   const entryLevel = resolveLogLevel(report, level);
+  if (!shouldLog(level, entryLevel)) {
+    return;
+  }
   sink.write({
     level: entryLevel,
-    message: `Risk analysis complete: ${report.level} (${report.score})`,
+    message: `Risk analysis: ${report.level} (score ${report.score})`,
     report,
-    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    context: includeContext ? sanitizeLogContext(context) : void 0
   });
 }
-function analyzeAndLog(guardian, options = {}) {
-  const report = guardian.analyze();
-  logReport(report, options);
+async function analyzeAndLog(guardian, context, options = {}) {
+  const report = await guardian.analyzeAsync(context);
+  logReport(report, { ...options, context });
   return report;
 }
+function sanitizeLogContext(context) {
+  if (context === null || context === void 0) {
+    return void 0;
+  }
+  if (typeof context !== "object") {
+    return void 0;
+  }
+  const record = context;
+  return {
+    method: typeof record.method === "string" ? record.method : void 0,
+    path: typeof record.path === "string" ? record.path : typeof record.originalUrl === "string" ? record.originalUrl : void 0,
+    ip: typeof record.ip === "string" ? record.ip : void 0
+  };
+}
 function resolveLogLevel(report, configured) {
   if (report.level === "CRITICAL") {
     return "error";
@@ -62,4 +99,5 @@ function shouldLog(configured, actual) {
 exports.analyzeAndLog = analyzeAndLog;
 exports.logReport = logReport;
 exports.loggerPlugin = loggerPlugin;
+exports.sanitizeLogContext = sanitizeLogContext;
 exports.shouldLog = shouldLog;

package/dist/index.d.cts

@@ -13,31 +13,23 @@ interface LogEntry {
     readonly message: string;
     readonly report: RiskReport;
     readonly timestamp: string;
+    readonly context?: unknown;
 }
-/** Options for the logger plugin (stub). */
+/** Options for the logger plugin. */
 interface LoggerPluginOptions {
-    /** Minimum level to emit. */
     readonly level?: LogLevel;
-    /** Custom sink. Defaults to console. */
     readonly sink?: LogSink;
-    /** Log only when score exceeds this threshold. */
     readonly minScore?: number;
+    /** Include redacted request metadata in logs (default: true). */
+    readonly includeContext?: boolean;
 }
-/**
- * Logger plugin for guardian-risk.
- *
- * @stub Future versions will hook into analyze() automatically.
- * For now, use `logReport()` after `guardian.analyze()`.
- */
 declare function loggerPlugin(options?: LoggerPluginOptions): Plugin;
-/**
- * Log a risk report to the configured sink.
- */
-declare function logReport(report: RiskReport, options?: LoggerPluginOptions): void;
-/**
- * Analyze and log in one step.
- */
-declare function analyzeAndLog(guardian: guardian_risk.Guardian, options?: LoggerPluginOptions): RiskReport;
+declare function logReport(report: RiskReport, options?: LoggerPluginOptions & {
+    context?: unknown;
+}): void;
+declare function analyzeAndLog(guardian: guardian_risk.Guardian, context?: unknown, options?: LoggerPluginOptions): Promise<RiskReport>;
+/** Redact sensitive request fields before logging. */
+declare function sanitizeLogContext(context: unknown): unknown;
 declare function shouldLog(configured: LogLevel, actual: LogLevel): boolean;
 
-export { type LogEntry, type LogLevel, type LogSink, type LoggerPluginOptions, analyzeAndLog, logReport, loggerPlugin, shouldLog };
+export { type LogEntry, type LogLevel, type LogSink, type LoggerPluginOptions, analyzeAndLog, logReport, loggerPlugin, sanitizeLogContext, shouldLog };

package/dist/index.d.ts

@@ -13,31 +13,23 @@ interface LogEntry {
     readonly message: string;
     readonly report: RiskReport;
     readonly timestamp: string;
+    readonly context?: unknown;
 }
-/** Options for the logger plugin (stub). */
+/** Options for the logger plugin. */
 interface LoggerPluginOptions {
-    /** Minimum level to emit. */
     readonly level?: LogLevel;
-    /** Custom sink. Defaults to console. */
     readonly sink?: LogSink;
-    /** Log only when score exceeds this threshold. */
     readonly minScore?: number;
+    /** Include redacted request metadata in logs (default: true). */
+    readonly includeContext?: boolean;
 }
-/**
- * Logger plugin for guardian-risk.
- *
- * @stub Future versions will hook into analyze() automatically.
- * For now, use `logReport()` after `guardian.analyze()`.
- */
 declare function loggerPlugin(options?: LoggerPluginOptions): Plugin;
-/**
- * Log a risk report to the configured sink.
- */
-declare function logReport(report: RiskReport, options?: LoggerPluginOptions): void;
-/**
- * Analyze and log in one step.
- */
-declare function analyzeAndLog(guardian: guardian_risk.Guardian, options?: LoggerPluginOptions): RiskReport;
+declare function logReport(report: RiskReport, options?: LoggerPluginOptions & {
+    context?: unknown;
+}): void;
+declare function analyzeAndLog(guardian: guardian_risk.Guardian, context?: unknown, options?: LoggerPluginOptions): Promise<RiskReport>;
+/** Redact sensitive request fields before logging. */
+declare function sanitizeLogContext(context: unknown): unknown;
 declare function shouldLog(configured: LogLevel, actual: LogLevel): boolean;
 
-export { type LogEntry, type LogLevel, type LogSink, type LoggerPluginOptions, analyzeAndLog, logReport, loggerPlugin, shouldLog };
+export { type LogEntry, type LogLevel, type LogSink, type LoggerPluginOptions, analyzeAndLog, logReport, loggerPlugin, sanitizeLogContext, shouldLog };

package/dist/index.js

@@ -13,37 +13,74 @@ var defaultSink = {
       score: entry.report.score,
       riskLevel: entry.report.level,
       matchedRules: entry.report.matchedRules.length,
-      timestamp: entry.timestamp
+      timestamp: entry.timestamp,
+      ...entry.context !== void 0 ? { context: entry.context } : {}
     });
     console.log(`[guardian-risk] ${payload}`);
   }
 };
 function loggerPlugin(options = {}) {
-  const { level = "info", sink = defaultSink, minScore = 0 } = options;
+  const resolved = {
+    level: "info",
+    sink: defaultSink,
+    minScore: 0,
+    includeContext: true,
+    ...options
+  };
   return {
     name: "guardian-risk-logger",
-    install(_guardian) {
+    install(guardian) {
+      guardian.afterAnalyze(({ report, data }) => {
+        logReport(report, {
+          ...resolved,
+          context: resolved.includeContext ? sanitizeLogContext(data) : void 0
+        });
+      });
     }
   };
 }
 function logReport(report, options = {}) {
-  const { level = "info", sink = defaultSink, minScore = 0 } = options;
+  const {
+    level = "info",
+    sink = defaultSink,
+    minScore = 0,
+    context,
+    includeContext = true
+  } = options;
   if (report.score < minScore) {
     return;
   }
   const entryLevel = resolveLogLevel(report, level);
+  if (!shouldLog(level, entryLevel)) {
+    return;
+  }
   sink.write({
     level: entryLevel,
-    message: `Risk analysis complete: ${report.level} (${report.score})`,
+    message: `Risk analysis: ${report.level} (score ${report.score})`,
     report,
-    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    context: includeContext ? sanitizeLogContext(context) : void 0
   });
 }
-function analyzeAndLog(guardian, options = {}) {
-  const report = guardian.analyze();
-  logReport(report, options);
+async function analyzeAndLog(guardian, context, options = {}) {
+  const report = await guardian.analyzeAsync(context);
+  logReport(report, { ...options, context });
   return report;
 }
+function sanitizeLogContext(context) {
+  if (context === null || context === void 0) {
+    return void 0;
+  }
+  if (typeof context !== "object") {
+    return void 0;
+  }
+  const record = context;
+  return {
+    method: typeof record.method === "string" ? record.method : void 0,
+    path: typeof record.path === "string" ? record.path : typeof record.originalUrl === "string" ? record.originalUrl : void 0,
+    ip: typeof record.ip === "string" ? record.ip : void 0
+  };
+}
 function resolveLogLevel(report, configured) {
   if (report.level === "CRITICAL") {
     return "error";
@@ -57,4 +94,4 @@ function shouldLog(configured, actual) {
   return LEVEL_ORDER[actual] >= LEVEL_ORDER[configured];
 }
 
-export { analyzeAndLog, logReport, loggerPlugin, shouldLog };
+export { analyzeAndLog, logReport, loggerPlugin, sanitizeLogContext, shouldLog };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guardian-risk-logger",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Audit logging plugin for guardian-risk — logs reports and matched rules",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -55,12 +55,12 @@
     "access": "public"
   },
   "peerDependencies": {
-    "guardian-risk": "^0.2.0"
+    "guardian-risk": "^0.3.0"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "guardian-risk": "0.2.1"
+    "guardian-risk": "0.3.0"
   },
   "scripts": {
     "build": "tsup",