@thotischner/observability-mcp 1.7.0 → 1.8.1

package/dist/net/egress-policy.js

@@ -25,6 +25,8 @@ export const EGRESS_ALLOWLIST = [
     { prefix: "connectors/", reason: "connectors query operator-configured source backends" },
     { prefix: "cli/index.ts", reason: "CLI fetches a source location the operator passed explicitly" },
     { prefix: "index.ts", reason: "connector-hub plugin install of an operator/registry-requested tarball URL" },
+    { prefix: "auth/oidc/", reason: "OIDC client calls the operator-configured OMCP_OIDC_ISSUER for discovery, JWKS, and code-exchange" },
+    { prefix: "auth/policy/", reason: "OpaPolicyEngine queries the operator-configured OMCP_OPA_URL on every RBAC decision" },
 ];
 /**
  * Hard-blocked analytics/telemetry SDKs — matches an *import/require of the

package/dist/openapi.js

@@ -51,6 +51,10 @@ export function buildOpenApiSpec(version) {
             { name: "settings", description: "Runtime server configuration." },
             { name: "metrics-config", description: "Per-source metric definitions." },
             { name: "self", description: "Server liveness and Prometheus metrics." },
+            { name: "auth", description: "Management-plane session login / logout / identity." },
+            { name: "audit", description: "Tamper-evident audit log of /api/* mutations." },
+            { name: "usage", description: "Per-identity rate-limit snapshot for /mcp callers." },
+            { name: "catalog", description: "Operator-curated service catalog." },
         ],
         paths: {
             "/api/sources": {
@@ -180,6 +184,442 @@ export function buildOpenApiSpec(version) {
                     responses: { "200": { description: "OpenAPI 3.1 document." } },
                 },
             },
+            "/api/info": {
+                get: {
+                    tags: ["self"],
+                    summary: "Server identity, build info, plugin list and governance posture.",
+                    description: "Anonymous-readable snapshot for external dashboards and discovery probes. " +
+                        "The `governance` block surfaces the active management-plane configuration " +
+                        "as booleans / rate-limit number only — no file paths, no session secret, " +
+                        "no user counts. Useful for alerting on \"this deployment silently reverted " +
+                        "to anonymous mode\" or \"redaction is off in prod\".",
+                    responses: {
+                        "200": {
+                            description: "Server info + governance posture.",
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object",
+                                        properties: {
+                                            name: { type: "string" },
+                                            version: { type: "string" },
+                                            mcpProtocolVersion: { type: "string" },
+                                            build: {
+                                                type: "object",
+                                                properties: {
+                                                    commit: { type: ["string", "null"] },
+                                                    date: { type: ["string", "null"] },
+                                                },
+                                            },
+                                            runtime: {
+                                                type: "object",
+                                                properties: {
+                                                    node: { type: "string" },
+                                                    platform: { type: "string" },
+                                                    arch: { type: "string" },
+                                                },
+                                            },
+                                            governance: {
+                                                type: "object",
+                                                description: "Active management-plane posture; booleans + rate-limit number only.",
+                                                properties: {
+                                                    authMode: { type: "string", enum: ["anonymous", "basic", "oidc"] },
+                                                    authSecretEphemeral: {
+                                                        type: "boolean",
+                                                        description: "True when OMCP_SESSION_SECRET is unset and the server minted an in-memory secret at boot. Sessions don't survive a restart.",
+                                                    },
+                                                    oidcIssuer: {
+                                                        type: "string",
+                                                        description: "Active OIDC issuer URL. Empty string when authMode is not 'oidc'. Never includes the client_secret.",
+                                                    },
+                                                    auditPersisted: {
+                                                        type: "boolean",
+                                                        description: "True when OMCP_MGMT_AUDIT_FILE is set; false means the audit log is the in-memory 500-entry ring.",
+                                                    },
+                                                    catalogConfigured: { type: "boolean" },
+                                                    redaction: { type: "boolean" },
+                                                    trustProxy: { type: "boolean" },
+                                                    toolRatePerMin: { type: "integer" },
+                                                },
+                                            },
+                                            plugins: {
+                                                type: "array",
+                                                items: {
+                                                    type: "object",
+                                                    properties: {
+                                                        name: { type: "string" },
+                                                        source: { type: "string" },
+                                                        version: { type: ["string", "null"] },
+                                                        signalTypes: { type: ["array", "null"], items: { type: "string" } },
+                                                    },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            "/api/me": {
+                get: {
+                    tags: ["auth"],
+                    summary: "Current identity, mode and granted permissions.",
+                    responses: {
+                        "200": {
+                            description: "Identity snapshot. `authenticated: false` in anonymous mode or when the session cookie is missing/invalid.",
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object",
+                                        properties: {
+                                            authenticated: { type: "boolean" },
+                                            mode: { type: "string", enum: ["anonymous", "basic", "oidc"] },
+                                            user: {
+                                                type: "object",
+                                                properties: {
+                                                    sub: { type: "string" },
+                                                    name: { type: "string" },
+                                                    email: { type: "string", description: "Present when the IdP supplied a verified email claim (OIDC mode)." },
+                                                    roles: { type: "array", items: { type: "string" } },
+                                                },
+                                            },
+                                            permissions: {
+                                                type: "array",
+                                                items: {
+                                                    type: "object",
+                                                    properties: {
+                                                        resource: { type: "string" },
+                                                        action: { type: "string", enum: ["read", "write", "delete", "bypass"] },
+                                                        // Resource enum is unconstrained at the OpenAPI level so
+                                                        // custom policies loaded via OMCP_RBAC_POLICY_FILE that
+                                                        // (correctly) include all built-in resources still validate.
+                                                    },
+                                                },
+                                            },
+                                            exp: { type: "integer", description: "Cookie expiry (seconds since epoch)." },
+                                            idpIssuer: {
+                                                type: "string",
+                                                description: "Active OIDC issuer URL. Present only when mode === \"oidc\". Useful for UI badges or IdP-side profile links.",
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            "/api/auth/login": {
+                post: {
+                    tags: ["auth"],
+                    summary: "Sign in (basic mode only).",
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["username", "password"],
+                                    properties: {
+                                        username: { type: "string" },
+                                        password: { type: "string", format: "password" },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        "200": { description: "Set-Cookie carries the signed session." },
+                        "400": { description: "Missing username or password." },
+                        "401": { description: "Invalid credentials." },
+                        "429": { description: "Too many login attempts." },
+                        "503": { description: "Server is in anonymous mode and does not accept logins." },
+                    },
+                },
+            },
+            "/api/auth/logout": {
+                post: {
+                    tags: ["auth"],
+                    summary: "Sign out — clears the session cookie.",
+                    responses: { "204": { description: "Cookie cleared." } },
+                },
+            },
+            "/api/auth/oidc/login": {
+                get: {
+                    tags: ["auth"],
+                    summary: "Redirect to the configured OIDC identity provider's authorization endpoint.",
+                    description: "Mounted only when OMCP_AUTH=oidc. Mints a short-lived flow cookie carrying state + nonce + PKCE code-verifier + return_to, then 302s the browser to the IdP.",
+                    parameters: [
+                        { name: "return_to", in: "query", required: false, schema: { type: "string" }, description: "Same-origin path to redirect to after a successful callback. Absolute URLs or scheme-relative paths are rejected." },
+                    ],
+                    responses: {
+                        "302": { description: "Redirect to the IdP authorize_endpoint." },
+                        "502": { description: "OIDC discovery failed (IdP unreachable / misconfigured)." },
+                    },
+                },
+            },
+            "/api/auth/oidc/callback": {
+                get: {
+                    tags: ["auth"],
+                    summary: "OIDC code-flow callback — exchanges code for an id_token and mints an OMCP session cookie.",
+                    description: "Verifies the state cookie, the IdP-returned state, the id_token signature (RS256/ES256), iss/aud/exp/nbf/nonce claims, then resolves OMCP roles from OMCP_OIDC_ROLES_CLAIM via OMCP_OIDC_ROLE_MAP and 302s to the cookie's return_to.",
+                    parameters: [
+                        { name: "code", in: "query", schema: { type: "string" } },
+                        { name: "state", in: "query", schema: { type: "string" } },
+                        { name: "error", in: "query", required: false, schema: { type: "string" } },
+                    ],
+                    responses: {
+                        "302": { description: "Authentication succeeded; session cookie set and redirected to return_to." },
+                        "400": { description: "Bad / expired / missing flow cookie, IdP error parameter present, or token exchange / verification failed." },
+                    },
+                },
+            },
+            "/api/auth/oidc/logout": {
+                post: {
+                    tags: ["auth"],
+                    summary: "Sign out of the OMCP session. Does not perform RP-initiated logout against the IdP.",
+                    description: "Clears the OMCP session cookie. To force an IdP-side sign-out, the UI should subsequently navigate to OMCP_OIDC_LOGOUT_REDIRECT (typically the IdP's end_session_endpoint).",
+                    responses: { "204": { description: "Cookie cleared." } },
+                },
+            },
+            "/api/audit": {
+                get: {
+                    tags: ["audit"],
+                    summary: "Recent management-plane audit entries (most recent first).",
+                    parameters: [
+                        { name: "from", in: "query", schema: { type: "string", format: "date-time" } },
+                        { name: "to", in: "query", schema: { type: "string", format: "date-time" } },
+                        { name: "actor", in: "query", schema: { type: "string" } },
+                        { name: "action", in: "query", schema: { type: "string" } },
+                        { name: "tenant", in: "query", schema: { type: "string" }, description: "Tenant scope. Non-admins are silently scoped to their own tenant; admins can pass any value (omit → all tenants)." },
+                        { name: "limit", in: "query", schema: { type: "integer", minimum: 1, maximum: 500, default: 100 } },
+                    ],
+                    responses: {
+                        "200": {
+                            description: "Audit feed plus the chain's tip hash.",
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object",
+                                        properties: {
+                                            entries: { type: "array", items: { type: "object", additionalProperties: true } },
+                                            tipHash: { type: "string" },
+                                            persisted: { type: "boolean" },
+                                            scopedTo: { type: ["string", "null"], description: "Tenant name this view is scoped to; null = all tenants (admin)." },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        "401": { description: "Unauthenticated (basic mode)." },
+                        "403": { description: "Missing audit:read permission." },
+                    },
+                },
+            },
+            "/api/usage": {
+                get: {
+                    tags: ["usage"],
+                    summary: "Per-identity windowed call count for /mcp callers.",
+                    parameters: [
+                        { name: "actor", in: "query", schema: { type: "string" }, description: "Narrow to a single identity." },
+                        { name: "tenant", in: "query", schema: { type: "string" }, description: "Tenant scope. Non-admins silently scoped to their own; admins can pick any (omit → all)." },
+                    ],
+                    responses: {
+                        "200": {
+                            description: "Usage snapshot. Anonymous /mcp traffic does not appear here.",
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object",
+                                        properties: {
+                                            identities: {
+                                                type: "array",
+                                                items: {
+                                                    type: "object",
+                                                    properties: {
+                                                        actor: { type: "string" },
+                                                        tenant: { type: "string", description: "Tenant the identity belongs to. 'default' when single-tenant." },
+                                                        count: { type: "integer" },
+                                                        limit: { type: "integer" },
+                                                        windowMs: { type: "integer" },
+                                                        tokens: {
+                                                            type: "object",
+                                                            description: "Per-identity 24h-rolling token usage. `limit: 0` means uncapped (OMCP_TOOL_DAILY_TOKENS unset).",
+                                                            properties: {
+                                                                used: { type: "integer" },
+                                                                limit: { type: "integer" },
+                                                                windowMs: { type: "integer" },
+                                                            },
+                                                        },
+                                                    },
+                                                },
+                                            },
+                                            defaultLimit: { type: "integer" },
+                                            windowMs: { type: "integer" },
+                                            tokens: {
+                                                type: "object",
+                                                description: "Process-wide defaults for the token-budget tracker.",
+                                                properties: {
+                                                    defaultLimit: { type: "integer" },
+                                                    windowMs: { type: "integer" },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        "403": { description: "Missing audit:read permission." },
+                    },
+                },
+            },
+            "/api/policy": {
+                get: {
+                    tags: ["auth"],
+                    summary: "Read-only view of the active RBAC policy (admin-only). Dry-run probe with ?resource=&action=&roles=.",
+                    parameters: [
+                        { name: "roles", in: "query", required: false, schema: { type: "string" }, description: "Comma-separated role names to probe. Defaults to none (treated as anonymous → always denied)." },
+                        { name: "resource", in: "query", required: false, schema: { type: "string" }, description: "Resource to probe. Pair with `action` to enter dry-run mode." },
+                        { name: "action", in: "query", required: false, schema: { type: "string" }, description: "Action to probe. Pair with `resource` to enter dry-run mode." },
+                    ],
+                    responses: {
+                        "200": {
+                            description: "Either the full policy map (no probe params) or a dry-run decision (with `resource` + `action`).",
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object",
+                                        properties: {
+                                            engine: { type: "string", description: "Identifier of the active engine: 'builtin', 'file:<path>', 'opa:<url>'." },
+                                            policy: { type: "object", additionalProperties: true },
+                                            roles: { type: "array", items: { type: "string" } },
+                                            note: { type: "string" },
+                                            dryRun: {
+                                                type: "object",
+                                                properties: {
+                                                    roles: { type: "array", items: { type: "string" } },
+                                                    resource: { type: "string" },
+                                                    action: { type: "string" },
+                                                    allowed: { type: "boolean" },
+                                                    reason: { type: "string" },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        "403": { description: "Missing users:delete permission (admin-only)." },
+                    },
+                },
+            },
+            "/api/products": {
+                get: {
+                    tags: ["products"],
+                    summary: "Loaded MCP Products catalogue (curated tool bundles for agents).",
+                    parameters: [
+                        { name: "tenant", in: "query", schema: { type: "string" }, description: "Tenant scope. Non-admins silently scoped to their own; admins can pick any (omit → all)." },
+                    ],
+                    responses: {
+                        "200": {
+                            description: "Products list scoped to caller's tenant; admins see staging entries too.",
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object",
+                                        properties: {
+                                            products: { type: "array", items: { type: "object", additionalProperties: true } },
+                                            configured: { type: "boolean" },
+                                            scopedTo: { type: ["string", "null"] },
+                                            includesStaging: { type: "boolean" },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        "403": { description: "Missing products:read permission." },
+                    },
+                },
+            },
+            "/api/products/{id}": {
+                get: {
+                    tags: ["products"],
+                    summary: "Single product by id (404 on cross-tenant or staging probe by non-admin).",
+                    parameters: [
+                        { name: "id", in: "path", required: true, schema: { type: "string" } },
+                    ],
+                    responses: {
+                        "200": { description: "The product entry.", content: { "application/json": { schema: { type: "object", additionalProperties: true } } } },
+                        "404": { description: "Not found (or hidden by tenant / staging scope)." },
+                        "403": { description: "Missing products:read permission." },
+                    },
+                },
+                put: {
+                    tags: ["products"],
+                    summary: "Upsert a product (admin + operator). Body must match the OMCP_PRODUCTS_FILE entry shape.",
+                    parameters: [
+                        { name: "id", in: "path", required: true, schema: { type: "string" } },
+                    ],
+                    requestBody: {
+                        required: true,
+                        content: { "application/json": { schema: { type: "object", additionalProperties: true } } },
+                    },
+                    responses: {
+                        "200": {
+                            description: "Upsert succeeded; returns the validated product + a persisted flag.",
+                            content: { "application/json": { schema: { type: "object", properties: {
+                                            product: { type: "object", additionalProperties: true },
+                                            persisted: { type: "boolean", description: "True when OMCP_PRODUCTS_FILE was set and the file was rewritten." },
+                                        } } } },
+                        },
+                        "400": { description: "Body shape invalid (validateProduct rejected — typo, unknown key, wrong type, ...)." },
+                        "403": { description: "Missing products:write permission, or non-admin attempting to write into another tenant." },
+                        "404": { description: "Existing product belongs to a different tenant (non-admin)." },
+                    },
+                },
+                delete: {
+                    tags: ["products"],
+                    summary: "Delete a product by id (admin only).",
+                    parameters: [
+                        { name: "id", in: "path", required: true, schema: { type: "string" } },
+                    ],
+                    responses: {
+                        "204": { description: "Deleted." },
+                        "403": { description: "Missing products:delete permission." },
+                        "404": { description: "Not found (or hidden by tenant scope)." },
+                    },
+                },
+            },
+            "/api/catalog": {
+                get: {
+                    tags: ["catalog"],
+                    summary: "Loaded service catalog (owner / tier / on-call / SLO).",
+                    parameters: [
+                        { name: "tenant", in: "query", schema: { type: "string" }, description: "Tenant scope. Non-admins silently scoped to their own; admins can pick any (omit → all)." },
+                    ],
+                    responses: {
+                        "200": {
+                            description: "Catalog map keyed by service name.",
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object",
+                                        properties: {
+                                            services: { type: "object", additionalProperties: true },
+                                            count: { type: "integer" },
+                                            configured: { type: "boolean", description: "true when OMCP_SERVICE_CATALOG_FILE is set." },
+                                            scopedTo: { type: ["string", "null"], description: "Tenant name this view is scoped to; null = all tenants (admin)." },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        "403": { description: "Missing catalog:read permission." },
+                    },
+                },
+            },
         },
     };
     return doc;

package/dist/openapi.test.d.ts

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

package/dist/openapi.test.js

@@ -0,0 +1,64 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildOpenApiSpec } from "./openapi.js";
+test("openapi — every user-visible /api path is documented", () => {
+    // If a future PR adds an endpoint here, also document it in
+    // openapi.ts. The list intentionally excludes admin-only routes the
+    // spec deliberately keeps internal — add to that allow-list rather
+    // than mass-adding routes to the spec.
+    const documentedRoutes = [
+        "/api/health",
+        "/api/services",
+        "/api/sources",
+        "/api/sources/{name}",
+        "/api/sources/{name}/metrics",
+        "/api/source-types",
+        "/api/settings",
+        "/api/health-thresholds",
+        "/api/me",
+        "/api/auth/login",
+        "/api/auth/logout",
+        "/api/auth/oidc/login",
+        "/api/auth/oidc/callback",
+        "/api/auth/oidc/logout",
+        "/api/audit",
+        "/api/usage",
+        "/api/policy",
+        "/api/catalog",
+        "/api/products",
+        "/api/products/{id}",
+        "/api/info",
+        "/api/openapi.json",
+    ];
+    const spec = buildOpenApiSpec("test-1.0.0");
+    const paths = Object.keys(spec.paths || {});
+    for (const route of documentedRoutes) {
+        assert.ok(paths.includes(route), `expected ${route} to be in the OpenAPI spec, paths=${paths.join(", ")}`);
+    }
+});
+test("openapi — /api/info governance block schema documents every field the handler returns", () => {
+    const spec = buildOpenApiSpec("test-1.0.0");
+    const info = spec.paths?.["/api/info"]?.get;
+    assert.ok(info, "/api/info should be documented");
+    // Walk down to the governance properties; the schema is inlined so
+    // we don't have to chase $refs.
+    const schema = info.responses["200"].content["application/json"].schema;
+    const gov = schema.properties?.governance?.properties;
+    assert.ok(gov, "governance block should be a documented object schema");
+    for (const field of [
+        "authMode",
+        "authSecretEphemeral",
+        "oidcIssuer",
+        "auditPersisted",
+        "catalogConfigured",
+        "redaction",
+        "trustProxy",
+        "toolRatePerMin",
+    ]) {
+        assert.ok(field in gov, `governance.${field} should be in the schema (got: ${Object.keys(gov).join(", ")})`);
+    }
+});
+test("openapi — info.version is the version string the caller passed in", () => {
+    const spec = buildOpenApiSpec("9.9.9-test");
+    assert.equal(spec.info?.version, "9.9.9-test");
+});

package/dist/policy/redact.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Conservative PII / secret redaction for tool outputs that may contain
+ * arbitrary log payloads.
+ *
+ * Scope of this module: pure string redaction with deterministic
+ * patterns. Returns the rewritten string plus a per-category count so
+ * callers can surface a "redacted N matches" hint to the user / agent
+ * without leaking what was matched. Designed to be safe-by-default
+ * (over-redact rather than under-redact) and explicit (each category
+ * tagged in the replacement marker, e.g. `[redacted-email]`).
+ *
+ * Bypass today is process-wide only: set `OMCP_REDACTION=off` if the
+ * upstream is already PII-clean. A per-request `redaction:bypass` RBAC
+ * permission for interactive admin sessions is on the roadmap — see
+ * docs/access-control.md "Why are my logs returning [redacted-email]?"
+ * and docs/redaction.md for the current state.
+ */
+export type RedactionCategory = "email" | "ipv4" | "ipv6" | "bearer" | "jwt" | "api-key" | "aws-key" | "slack-token" | "private-key" | "gh-pat" | "credit-card";
+export interface RedactionResult {
+    text: string;
+    matches: Record<RedactionCategory, number>;
+    totalMatches: number;
+}
+/** Run all patterns in a deterministic order; later patterns won't
+ * re-match content already replaced by an earlier one (the marker
+ * starts with `[redacted-` which none of the patterns match). */
+export declare function redactText(input: string): RedactionResult;
+/** Maximum nesting depth the walker will descend into. Operational
+ * log payloads are essentially flat (objects of strings + a few
+ * nested arrays); a pathologically deep structure is almost certainly
+ * a bug or an attack, and stack-overflowing the auth path is worse
+ * than truncating. The cap is generous — well above anything a
+ * Prometheus / Loki record would ever produce. */
+export declare const MAX_REDACT_DEPTH = 64;
+/** Walk an arbitrary parsed-JSON value and redact every string leaf,
+ * accumulating match counts. Non-string leaves and structural keys are
+ * left untouched. Returns a new value (does not mutate input). Bails
+ * out below `MAX_REDACT_DEPTH` levels of nesting and returns the raw
+ * sub-tree untouched at that point. */
+export declare function redactValue(input: unknown): {
+    value: unknown;
+    matches: Record<RedactionCategory, number>;
+    totalMatches: number;
+};