@thotischner/observability-mcp 3.0.1 → 3.1.1

package/dist/security/csp.js

@@ -0,0 +1,135 @@
+/**
+ * Content-Security-Policy for the management-plane Web UI.
+ *
+ * Two policies ship together, by design:
+ *
+ *  - **Enforced** (`Content-Security-Policy`): a real, non-breaking policy.
+ *    It locks down everything the UI doesn't need — no remote scripts
+ *    (`script-src 'self'`), no plugins (`object-src 'none'`), no `<base>`
+ *    hijack (`base-uri 'self'`), no framing (`frame-ancestors 'none'`),
+ *    and same-origin-only XHR via `connect-src 'self'`. It keeps
+ *    `'unsafe-inline'` for `script-src` because the single-file UI uses
+ *    ~200 inline event-handler attributes (`onclick=`, …) that a nonce
+ *    cannot cover — a nonce in `script-src` would *disable* `'unsafe-inline'`
+ *    in CSP3 and break every button. So the enforced policy is a genuine
+ *    improvement over no CSP without regressing the UI.
+ *
+ *  - **Report-Only** (`Content-Security-Policy-Report-Only`): the strict
+ *    target policy — `script-src 'self' 'nonce-…'`, no `'unsafe-inline'`.
+ *    The two legitimate inline `<script>` blocks carry the per-request
+ *    nonce, so this policy flags ONLY the inline event-handler debt. It
+ *    blocks nothing; it just reports, giving an actionable migration list
+ *    (move the handlers to addEventListener) before a future slice can
+ *    promote the strict policy to enforced.
+ *
+ *    It is **opt-in** (`OMCP_CSP_STRICT_REPORT=true`): with ~200 inline
+ *    handlers it would otherwise emit a `[Report Only]` console message
+ *    per handler on every page load — noise an operator with devtools
+ *    open shouldn't eat by default. Enable it when you're actively
+ *    working the migration. The enforced policy + reporting endpoint are
+ *    always on regardless.
+ *
+ * Both policies report to `/api/csp-violations` via the modern Reporting
+ * API (`Reporting-Endpoints` + `report-to`) and the legacy `report-uri`.
+ */
+import { randomBytes } from "node:crypto";
+/** Placeholder substituted with the per-request nonce when serving the UI HTML. */
+export const CSP_NONCE_PLACEHOLDER = "__CSP_NONCE__";
+/** The named reporting group used in the Report-To / Reporting-Endpoints headers. */
+export const CSP_REPORT_GROUP = "omcp-csp";
+/** Where violation reports are POSTed. */
+export const CSP_REPORT_PATH = "/api/csp-violations";
+/** Fresh base64 nonce (128 bits). */
+export function generateNonce() {
+    return randomBytes(16).toString("base64");
+}
+/** The enforced policy — non-breaking, keeps the UI working. */
+export function enforcedCsp() {
+    return [
+        "default-src 'self'",
+        "base-uri 'self'",
+        "object-src 'none'",
+        "frame-ancestors 'none'",
+        "form-action 'self'",
+        "script-src 'self' 'unsafe-inline'",
+        "style-src 'self' 'unsafe-inline'",
+        "img-src 'self' data:",
+        "font-src 'self' data:",
+        "connect-src 'self'",
+        `report-uri ${CSP_REPORT_PATH}`,
+        `report-to ${CSP_REPORT_GROUP}`,
+    ].join("; ");
+}
+/** The strict target policy, run in report-only mode against the nonce. */
+export function reportOnlyCsp(nonce) {
+    return [
+        "default-src 'self'",
+        "base-uri 'self'",
+        "object-src 'none'",
+        "frame-ancestors 'none'",
+        "form-action 'self'",
+        `script-src 'self' 'nonce-${nonce}'`,
+        "style-src 'self' 'unsafe-inline'",
+        "img-src 'self' data:",
+        "font-src 'self' data:",
+        "connect-src 'self'",
+        `report-uri ${CSP_REPORT_PATH}`,
+        `report-to ${CSP_REPORT_GROUP}`,
+    ].join("; ");
+}
+/** Whether the strict Report-Only policy is enabled. Default off — see
+ *  the module header for why (console noise from ~200 inline handlers). */
+export function cspStrictReportFromEnv(env = process.env) {
+    const v = env.OMCP_CSP_STRICT_REPORT?.trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+/** Value for the modern `Reporting-Endpoints` header. */
+export function reportingEndpointsHeader() {
+    return `${CSP_REPORT_GROUP}="${CSP_REPORT_PATH}"`;
+}
+/** Value for the legacy `Report-To` header (Reporting API v0). */
+export function reportToHeader() {
+    return JSON.stringify({
+        group: CSP_REPORT_GROUP,
+        max_age: 10886400,
+        endpoints: [{ url: CSP_REPORT_PATH }],
+    });
+}
+/**
+ * Normalise a posted CSP violation (either the legacy
+ * `application/csp-report` `{ "csp-report": {...} }` envelope or a modern
+ * Reporting-API `application/reports+json` array element) into a compact,
+ * log-safe summary. Returns null when the body isn't a recognisable report.
+ */
+export function summariseViolation(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    // Reporting API delivers an array of { type, body: {...} }.
+    if (Array.isArray(body)) {
+        for (const item of body) {
+            const s = summariseViolation(item);
+            if (s)
+                return s;
+        }
+        return null;
+    }
+    const o = body;
+    // Reporting-API single report: { type: "csp-violation", body: {...} }.
+    const report = (o["csp-report"] ?? o.body ?? o);
+    if (!report || typeof report !== "object")
+        return null;
+    const pick = (...keys) => {
+        for (const k of keys) {
+            const v = report[k];
+            if (typeof v === "string" && v)
+                return v.slice(0, 256);
+        }
+        return "";
+    };
+    const directive = pick("effective-directive", "effectiveDirective", "violated-directive", "violatedDirective");
+    const blockedUri = pick("blocked-uri", "blockedURL", "blockedURI");
+    const documentUri = pick("document-uri", "documentURL", "documentURI");
+    if (!directive && !blockedUri && !documentUri)
+        return null;
+    return { directive, blockedUri, documentUri };
+}

package/dist/security/csp.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/security/csp.test.js

@@ -0,0 +1,97 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { generateNonce, enforcedCsp, reportOnlyCsp, reportingEndpointsHeader, reportToHeader, summariseViolation, cspStrictReportFromEnv, CSP_NONCE_PLACEHOLDER, CSP_REPORT_GROUP, CSP_REPORT_PATH, } from "./csp.js";
+test("generateNonce returns a fresh base64 value each call", () => {
+    const a = generateNonce();
+    const b = generateNonce();
+    assert.notEqual(a, b);
+    assert.match(a, /^[A-Za-z0-9+/]+=*$/);
+    // 16 bytes → 24 base64 chars (with padding).
+    assert.ok(a.length >= 22);
+});
+test("enforced policy keeps the UI working but locks the rest down", () => {
+    const csp = enforcedCsp();
+    // Inline handlers survive: unsafe-inline present, NO nonce (which would disable it).
+    assert.match(csp, /script-src 'self' 'unsafe-inline'/);
+    assert.ok(!csp.includes("nonce-"), "enforced policy must not carry a nonce");
+    // Hard locks.
+    assert.match(csp, /object-src 'none'/);
+    assert.match(csp, /base-uri 'self'/);
+    assert.match(csp, /frame-ancestors 'none'/);
+    assert.match(csp, /default-src 'self'/);
+    assert.match(csp, /connect-src 'self'/);
+    // Reporting wired both ways.
+    assert.match(csp, new RegExp(`report-uri ${CSP_REPORT_PATH}`));
+    assert.match(csp, new RegExp(`report-to ${CSP_REPORT_GROUP}`));
+});
+test("report-only policy is strict and nonce-bound, no unsafe-inline on scripts", () => {
+    const nonce = generateNonce();
+    const csp = reportOnlyCsp(nonce);
+    assert.match(csp, new RegExp(`script-src 'self' 'nonce-${nonce.replace(/[+/]/g, "\\$&")}'`));
+    // Strict: the script directive must NOT allow unsafe-inline.
+    const scriptDirective = csp.split(";").find((d) => d.trim().startsWith("script-src"));
+    assert.ok(!scriptDirective.includes("unsafe-inline"));
+    assert.match(csp, /object-src 'none'/);
+});
+test("reporting headers name the same group + endpoint", () => {
+    assert.equal(reportingEndpointsHeader(), `${CSP_REPORT_GROUP}="${CSP_REPORT_PATH}"`);
+    const parsed = JSON.parse(reportToHeader());
+    assert.equal(parsed.group, CSP_REPORT_GROUP);
+    assert.equal(parsed.endpoints[0].url, CSP_REPORT_PATH);
+    assert.ok(parsed.max_age > 0);
+});
+test("the nonce placeholder is a stable token", () => {
+    assert.equal(CSP_NONCE_PLACEHOLDER, "__CSP_NONCE__");
+});
+test("strict report-only is opt-in (default off)", () => {
+    assert.equal(cspStrictReportFromEnv({}), false);
+    assert.equal(cspStrictReportFromEnv({ OMCP_CSP_STRICT_REPORT: "true" }), true);
+    assert.equal(cspStrictReportFromEnv({ OMCP_CSP_STRICT_REPORT: "1" }), true);
+    assert.equal(cspStrictReportFromEnv({ OMCP_CSP_STRICT_REPORT: "no" }), false);
+    assert.equal(cspStrictReportFromEnv({ OMCP_CSP_STRICT_REPORT: "false" }), false);
+});
+test("summariseViolation parses the legacy csp-report envelope", () => {
+    const s = summariseViolation({
+        "csp-report": {
+            "effective-directive": "script-src-attr",
+            "blocked-uri": "inline",
+            "document-uri": "https://gw.example/",
+            "extra": "ignored",
+        },
+    });
+    assert.deepEqual(s, {
+        directive: "script-src-attr",
+        blockedUri: "inline",
+        documentUri: "https://gw.example/",
+    });
+});
+test("summariseViolation parses a modern Reporting-API array", () => {
+    const s = summariseViolation([
+        {
+            type: "csp-violation",
+            body: {
+                effectiveDirective: "script-src-elem",
+                blockedURL: "https://evil.example/x.js",
+                documentURL: "https://gw.example/",
+            },
+        },
+    ]);
+    assert.equal(s?.directive, "script-src-elem");
+    assert.equal(s?.blockedUri, "https://evil.example/x.js");
+});
+test("summariseViolation falls back to violated-directive", () => {
+    const s = summariseViolation({ "csp-report": { "violated-directive": "img-src", "blocked-uri": "data" } });
+    assert.equal(s?.directive, "img-src");
+});
+test("summariseViolation returns null for junk", () => {
+    assert.equal(summariseViolation(null), null);
+    assert.equal(summariseViolation("nope"), null);
+    assert.equal(summariseViolation({}), null);
+    assert.equal(summariseViolation({ random: "field" }), null);
+});
+test("summariseViolation truncates over-long fields", () => {
+    const long = "a".repeat(5000);
+    const s = summariseViolation({ "csp-report": { "blocked-uri": long } });
+    assert.ok(s);
+    assert.ok((s.blockedUri).length <= 256);
+});

package/dist/tools/query-logs-schema.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/query-logs-schema.test.js

@@ -0,0 +1,38 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+// Regression guard for issue #415: the query_logs handler (query-logs.ts)
+// reads `labels` and `aggregate` from its args, and validateLogLabels /
+// validateLogAggregate enforce them — but the MCP-facing input schema is
+// declared INLINE in createMcpServer's registerTool("query_logs", …) block
+// in index.ts. In v3.1.0 that inline schema was never updated to advertise
+// `labels`/`aggregate`, so the MCP SDK stripped those keys before they
+// reached the handler: the params were unreachable over MCP and passing
+// them was a silent no-op. The handler unit tests passed because they call
+// the handler directly, bypassing the SDK schema layer.
+//
+// This test parses index.ts and asserts the query_logs registration block
+// declares both fields as schema entries, so the SDK validates and forwards
+// them. The live equivalent (real tools/list handshake) lives in the
+// conformance suite; this is the fast, server-less guard.
+const here = dirname(fileURLToPath(import.meta.url));
+const INDEX_TS = join(here, "..", "index.ts");
+function registerToolBlock(src, tool) {
+    const start = src.indexOf(`registerTool(\n    "${tool}"`);
+    assert.notEqual(start, -1, `registerTool("${tool}", …) not found in index.ts`);
+    // The block ends at the next registerTool( call (or EOF).
+    const next = src.indexOf("registerTool(", start + 1);
+    return src.slice(start, next === -1 ? undefined : next);
+}
+test("query_logs MCP schema advertises `labels` (issue #415 #1)", () => {
+    const block = registerToolBlock(readFileSync(INDEX_TS, "utf8"), "query_logs");
+    assert.match(block, /\blabels:\s*z\b/, "query_logs registration in index.ts must declare a `labels` schema field " +
+        "so the MCP SDK forwards it to the handler (else it is silently stripped).");
+});
+test("query_logs MCP schema advertises `aggregate` (issue #415 #2)", () => {
+    const block = registerToolBlock(readFileSync(INDEX_TS, "utf8"), "query_logs");
+    assert.match(block, /\baggregate:\s*z\b/, "query_logs registration in index.ts must declare an `aggregate` schema field " +
+        "so the MCP SDK forwards it to the handler (else it is silently stripped).");
+});

package/dist/tools/query-logs.d.ts

@@ -22,10 +22,43 @@ export declare const queryLogsDefinition: {
                 type: string;
                 description: string;
             };
+            labels: {
+                type: string;
+                additionalProperties: {
+                    type: string;
+                };
+                description: string;
+            };
             limit: {
                 type: string;
                 description: string;
             };
+            aggregate: {
+                type: string;
+                description: string;
+                properties: {
+                    op: {
+                        type: string;
+                        enum: string[];
+                    };
+                    by: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                        description: string;
+                    };
+                    k: {
+                        type: string;
+                        description: string;
+                    };
+                    step: {
+                        type: string;
+                        description: string;
+                    };
+                };
+                required: string[];
+            };
         };
         required: string[];
     };
@@ -36,6 +69,13 @@ export declare function queryLogsHandler(registry: ConnectorRegistry, args: {
     duration?: string;
     level?: string;
     limit?: number;
+    labels?: Record<string, string>;
+    aggregate?: {
+        op: "count_over_time" | "sum" | "topk";
+        by?: string[];
+        k?: number;
+        step?: string;
+    };
 }, ctx?: RequestContext): Promise<{
     content: {
         type: "text";

package/dist/tools/query-logs.js

@@ -1,8 +1,8 @@
 import { defaultContext } from "../context.js";
-import { validateDuration, validateServiceName, errorResponse } from "./validation.js";
+import { validateDuration, validateServiceName, validateLogLabels, validateLogAggregate, errorResponse } from "./validation.js";
 export const queryLogsDefinition = {
     name: "query_logs",
-    description: "Query logs for a service over a given timeframe. Returns log entries with a summary including error/warning counts and top error patterns. Supports filtering by log level and search query.",
+    description: "Query logs for a service over a given timeframe. Returns log entries with a summary including error/warning counts and top error patterns. Filter by log level, a free-text/regex search, OR structured `labels` (exact-match on backend-extracted fields like method/status/url/environment — far more reliable than regex on structured JSON logs).",
     inputSchema: {
         type: "object",
         properties: {
@@ -22,9 +22,25 @@ export const queryLogsDefinition = {
                 type: "string",
                 description: "Filter by log level: 'error', 'warn', 'info', 'debug'",
             },
+            labels: {
+                type: "object",
+                additionalProperties: { type: "string" },
+                description: "Structured equality filters on backend-extracted fields, AND'd together, e.g. {\"method\":\"GET\",\"url\":\"/\",\"status\":\"200\",\"environment\":\"prod\"}. Prefer this over `query` for structured JSON logs — the literal text rarely appears verbatim. Label names must be [a-zA-Z_][a-zA-Z0-9_]* (max 20).",
+            },
             limit: {
                 type: "number",
-                description: "Maximum number of log entries to return. Default: 100",
+                description: "Maximum number of log entries to return. Default: 100. Ignored when `aggregate` is set.",
+            },
+            aggregate: {
+                type: "object",
+                description: "Server-side aggregation — returns grouped counts, not raw rows, so you get a number instead of a haystack. op: 'count_over_time' (time series of counts per bucket), 'sum' (total per group over the window), 'topk' (top-k groups by total). Example: {\"op\":\"topk\",\"by\":[\"url\"],\"k\":10} for the busiest paths. Honours `labels`/`query` filters.",
+                properties: {
+                    op: { type: "string", enum: ["count_over_time", "sum", "topk"] },
+                    by: { type: "array", items: { type: "string" }, description: "Group-by label names (required for topk)." },
+                    k: { type: "number", description: "Top-k count (default 10)." },
+                    step: { type: "string", description: "Bucket size for count_over_time, e.g. '15m'. Defaults to ~1/60th of the window." },
+                },
+                required: ["op"],
             },
         },
         required: ["service"],
@@ -38,6 +54,12 @@ export async function queryLogsHandler(registry, args, ctx = defaultContext()) {
     const durationErr = validateDuration(duration);
     if (durationErr)
         return errorResponse(durationErr);
+    const labelsErr = validateLogLabels(args.labels);
+    if (labelsErr)
+        return errorResponse(labelsErr);
+    const aggErr = validateLogAggregate(args.aggregate);
+    if (aggErr)
+        return errorResponse(aggErr);
     const connectors = registry.getByTenant(ctx.tenant).filter((c) => c.signalType === "logs");
     if (connectors.length === 0) {
         return {
@@ -47,6 +69,49 @@ export async function queryLogsHandler(registry, args, ctx = defaultContext()) {
             isError: true,
         };
     }
+    // Aggregate mode (Q-LOG2): route to the connector's queryLogAggregate.
+    if (args.aggregate) {
+        const aggResults = [];
+        const aggErrors = [];
+        let capable = 0;
+        for (const connector of connectors) {
+            if (!connector.queryLogAggregate)
+                continue;
+            capable++;
+            try {
+                const q = {
+                    service: args.service,
+                    duration,
+                    labels: args.labels,
+                    query: args.query,
+                    op: args.aggregate.op,
+                    by: args.aggregate.by,
+                    k: args.aggregate.k,
+                    step: args.aggregate.step,
+                };
+                aggResults.push(await connector.queryLogAggregate(q));
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(`Log aggregate failed on ${connector.name}:`, msg);
+                aggErrors.push(`${connector.name}: ${msg}`);
+            }
+        }
+        if (capable === 0) {
+            return errorResponse("No log backend supports aggregation (queryLogAggregate).");
+        }
+        if (aggResults.length === 0) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: aggErrors.length ? `Aggregate failed: ${aggErrors.join("; ")}` : "No data returned", service: args.service, duration }) }],
+                isError: aggErrors.length > 0,
+            };
+        }
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(aggResults.length === 1 ? aggResults[0] : aggResults, null, 2) },
+            ],
+        };
+    }
     const results = [];
     const errors = [];
     for (const connector of connectors) {
@@ -59,6 +124,7 @@ export async function queryLogsHandler(registry, args, ctx = defaultContext()) {
                 duration,
                 level: args.level,
                 limit: args.limit,
+                labels: args.labels,
             });
             results.push(result);
         }

package/dist/tools/validation.d.ts

@@ -8,6 +8,19 @@ export declare function validateMetricName(metric: string, registry: ConnectorRe
  */
 export declare function sanitizeLabelValue(value: string): string | null;
 export declare function validateServiceName(service: string): string | null;
+/**
+ * Validate a structured `labels` filter map for query_logs. Fail-closed:
+ * any bad key/value rejects the whole request rather than silently
+ * dropping a filter (a dropped filter could widen results past what the
+ * caller intended). Bounds the map size + value length so a crafted input
+ * can't build a pathological query.
+ */
+export declare function validateLogLabels(labels: unknown): string | null;
+/**
+ * Validate the query_logs `aggregate` spec. Fail-closed, like the labels
+ * validator. Returns an error string or null.
+ */
+export declare function validateLogAggregate(aggregate: unknown): string | null;
 export declare function errorResponse(message: string): {
     content: {
         type: "text";

package/dist/tools/validation.js

@@ -41,6 +41,80 @@ export function validateServiceName(service) {
     }
     return null;
 }
+/** A Prometheus/Loki label name: letter/underscore, then word chars. */
+const LABEL_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/**
+ * Validate a structured `labels` filter map for query_logs. Fail-closed:
+ * any bad key/value rejects the whole request rather than silently
+ * dropping a filter (a dropped filter could widen results past what the
+ * caller intended). Bounds the map size + value length so a crafted input
+ * can't build a pathological query.
+ */
+export function validateLogLabels(labels) {
+    if (labels === undefined)
+        return null;
+    if (typeof labels !== "object" || labels === null || Array.isArray(labels)) {
+        return "Invalid labels: must be an object mapping label names to string values.";
+    }
+    const entries = Object.entries(labels);
+    if (entries.length > 20) {
+        return "Too many labels (max 20).";
+    }
+    for (const [k, v] of entries) {
+        if (!LABEL_NAME_RE.test(k)) {
+            return `Invalid label name "${k}". Must match [a-zA-Z_][a-zA-Z0-9_]* (no dots, dashes, or quotes).`;
+        }
+        if (typeof v !== "string") {
+            return `Invalid value for label "${k}": must be a string.`;
+        }
+        if (v.length > 1024) {
+            return `Value for label "${k}" too long (max 1024 chars).`;
+        }
+    }
+    return null;
+}
+const AGGREGATE_OPS = new Set(["count_over_time", "sum", "topk"]);
+/**
+ * Validate the query_logs `aggregate` spec. Fail-closed, like the labels
+ * validator. Returns an error string or null.
+ */
+export function validateLogAggregate(aggregate) {
+    if (aggregate === undefined)
+        return null;
+    if (typeof aggregate !== "object" || aggregate === null || Array.isArray(aggregate)) {
+        return "Invalid aggregate: must be an object with an `op`.";
+    }
+    const a = aggregate;
+    if (typeof a.op !== "string" || !AGGREGATE_OPS.has(a.op)) {
+        return `Invalid aggregate.op. Must be one of: ${[...AGGREGATE_OPS].join(", ")}.`;
+    }
+    if (a.by !== undefined) {
+        if (!Array.isArray(a.by) || !a.by.every((x) => typeof x === "string")) {
+            return "aggregate.by must be an array of label-name strings.";
+        }
+        if (a.by.length > 10)
+            return "aggregate.by has too many labels (max 10).";
+        for (const name of a.by) {
+            if (!LABEL_NAME_RE.test(name)) {
+                return `Invalid aggregate.by label "${name}". Must match [a-zA-Z_][a-zA-Z0-9_]*.`;
+            }
+        }
+    }
+    if (a.k !== undefined) {
+        if (typeof a.k !== "number" || !Number.isFinite(a.k) || a.k <= 0 || a.k > 1000) {
+            return "aggregate.k must be a positive integer (max 1000).";
+        }
+    }
+    if (a.step !== undefined) {
+        if (typeof a.step !== "string" || validateDuration(a.step)) {
+            return "aggregate.step must be a duration like '15m', '1h'.";
+        }
+    }
+    if (a.op === "topk" && (a.by === undefined || a.by.length === 0)) {
+        return "aggregate.op 'topk' requires at least one `by` label to rank.";
+    }
+    return null;
+}
 export function errorResponse(message) {
     return {
         content: [{ type: "text", text: JSON.stringify({ error: message }) }],

package/dist/tools/validation.test.js

@@ -1,6 +1,59 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { validateDuration, validateServiceName, sanitizeLabelValue, errorResponse } from "./validation.js";
+import { validateDuration, validateServiceName, sanitizeLabelValue, validateLogLabels, validateLogAggregate, errorResponse } from "./validation.js";
+describe("validateLogAggregate (Q-LOG2)", () => {
+    it("accepts undefined and valid specs", () => {
+        assert.equal(validateLogAggregate(undefined), null);
+        assert.equal(validateLogAggregate({ op: "count_over_time" }), null);
+        assert.equal(validateLogAggregate({ op: "sum", by: ["url", "status"] }), null);
+        assert.equal(validateLogAggregate({ op: "topk", by: ["url"], k: 5, step: "15m" }), null);
+    });
+    it("rejects a bad/missing op", () => {
+        assert.ok(validateLogAggregate({}));
+        assert.ok(validateLogAggregate({ op: "median" }));
+        assert.ok(validateLogAggregate("nope"));
+    });
+    it("rejects bad by labels", () => {
+        assert.ok(validateLogAggregate({ op: "sum", by: ["a.b"] }));
+        assert.ok(validateLogAggregate({ op: "sum", by: "url" }));
+    });
+    it("rejects bad k and step", () => {
+        assert.ok(validateLogAggregate({ op: "topk", by: ["url"], k: 0 }));
+        assert.ok(validateLogAggregate({ op: "topk", by: ["url"], k: 99999 }));
+        assert.ok(validateLogAggregate({ op: "count_over_time", step: "soon" }));
+    });
+    it("requires a by label for topk", () => {
+        assert.ok(validateLogAggregate({ op: "topk" }));
+        assert.ok(validateLogAggregate({ op: "topk", by: [] }));
+    });
+});
+describe("validateLogLabels (Q-LOG1)", () => {
+    it("accepts undefined (no filter) and a valid map", () => {
+        assert.equal(validateLogLabels(undefined), null);
+        assert.equal(validateLogLabels({ method: "GET", status: "200", environment: "prod" }), null);
+    });
+    it("rejects non-object inputs", () => {
+        assert.ok(validateLogLabels("nope"));
+        assert.ok(validateLogLabels(["a"]));
+        assert.ok(validateLogLabels(42));
+    });
+    it("rejects label names with dots, dashes, or quotes (injection-safe, fail-closed)", () => {
+        assert.ok(validateLogLabels({ "a.b": "x" }));
+        assert.ok(validateLogLabels({ "a-b": "x" }));
+        assert.ok(validateLogLabels({ 'a"x': "y" }));
+        assert.ok(validateLogLabels({ "1abc": "x" })); // can't start with a digit
+    });
+    it("rejects non-string and over-long values", () => {
+        assert.ok(validateLogLabels({ method: 123 }));
+        assert.ok(validateLogLabels({ method: "x".repeat(1025) }));
+    });
+    it("rejects too many labels", () => {
+        const many = {};
+        for (let i = 0; i < 21; i++)
+            many[`k${i}`] = "v";
+        assert.ok(validateLogLabels(many));
+    });
+});
 describe("validateDuration", () => {
     it("accepts valid durations", () => {
         assert.equal(validateDuration("5m"), null);

package/dist/types.d.ts

@@ -109,6 +109,54 @@ export interface LogQuery {
     duration: string;
     limit?: number;
     level?: string;
+    /** Structured label/field equality filters, AND'd together. For Loki
+     *  these compile to LogQL label-filter expressions after `| json`, so
+     *  fields the backend already extracts (method, status, url, ip,
+     *  environment, …) become first-class selectors instead of brittle
+     *  free-text regex. */
+    labels?: Record<string, string>;
+}
+/** Server-side log aggregation (Q-LOG2). Pushes count/group/topk down to
+ *  the backend's metric-query path so an agent gets a *number*, not a
+ *  *haystack*. */
+export interface LogAggregateQuery {
+    service: string;
+    duration: string;
+    /** Same structured filters as LogQuery, applied before aggregation. */
+    labels?: Record<string, string>;
+    /** Optional line filter applied before aggregation. */
+    query?: string;
+    /** count_over_time → time series of counts per bucket; sum → total per
+     *  group over the window; topk → the top-k groups by total. */
+    op: "count_over_time" | "sum" | "topk";
+    /** Group-by label names. */
+    by?: string[];
+    /** k for topk (default 10). */
+    k?: number;
+    /** Bucket size for count_over_time, e.g. "15m". Defaults to the window. */
+    step?: string;
+}
+export interface LogAggregateSeries {
+    /** The group key (the `by` label values). Empty object for an ungrouped total. */
+    labels: Record<string, string>;
+    /** Single value — present for instant ops (sum / topk). */
+    value?: number;
+    /** Time series — present for count_over_time. */
+    points?: Array<{
+        t: number;
+        value: number;
+    }>;
+}
+export interface LogAggregateResult {
+    source: string;
+    op: string;
+    by: string[];
+    step?: string;
+    /** "instant" (vector) for sum/topk, "range" (matrix) for count_over_time. */
+    mode: "instant" | "range";
+    series: LogAggregateSeries[];
+    /** Operator-facing notes, e.g. that `limit` is ignored in aggregate mode. */
+    note?: string;
 }
 export interface DataPoint {
     timestamp: string;