@datasynx/agentic-ai-cartography 2.2.0 → 2.4.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import Database from 'better-sqlite3';
 import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import http from 'node:http';
+import http, { IncomingMessage, Server } from 'node:http';
 import { McpServerConfig, HookCallback } from '@anthropic-ai/claude-agent-sdk';
 
 /**
@@ -390,14 +390,22 @@ interface DriftAlert {
     /** ISO-8601 UTC generation time. */
     generatedAt: string;
 }
-/** One configured drift sink. `url` is required when `type === 'webhook'`. */
+/** One configured drift sink. `url` is required for every type except `stdout`. */
 interface DriftSinkConfig {
-    type: 'stdout' | 'webhook';
-    /** Required when type === 'webhook'. */
+    type: 'stdout' | 'webhook' | 'slack' | 'pagerduty' | 'jira';
+    /** Required for `webhook`/`slack`/`jira`; optional for `pagerduty` (defaults to the Events API). */
     url?: string;
-    /** Optional bearer token; falls back to CARTOGRAPHY_DRIFT_TOKEN. */
+    /** Bearer token (`webhook`) / Jira API token (`jira`); falls back to CARTOGRAPHY_DRIFT_TOKEN. */
     token?: string;
     timeoutMs?: number;
+    /** PagerDuty Events API v2 routing key (rides in the body). Falls back to `token`/CARTOGRAPHY_DRIFT_TOKEN. */
+    routingKey?: string;
+    /** Jira account email (basic-auth user). */
+    email?: string;
+    /** Jira target project key, e.g. "OPS". */
+    project?: string;
+    /** Jira issue type name (default "Task"). */
+    issueType?: string;
 }
 /**
  * Opt-in drift-alerting block on {@link CartographyConfig}. Absent → the runner
@@ -420,10 +428,17 @@ declare const DriftConfigSchema: z.ZodObject<{
         type: z.ZodEnum<{
             stdout: "stdout";
             webhook: "webhook";
+            slack: "slack";
+            pagerduty: "pagerduty";
+            jira: "jira";
         }>;
         url: z.ZodOptional<z.ZodString>;
         token: z.ZodOptional<z.ZodString>;
         timeoutMs: z.ZodOptional<z.ZodNumber>;
+        routingKey: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        project: z.ZodOptional<z.ZodString>;
+        issueType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 /** Machine-readable result formats shared by `discover` (#67) and `schedule`. */
@@ -1378,6 +1393,92 @@ declare class SqliteStoreBackend implements StoreBackend {
     close(): void;
 }
 
+/**
+ * `QueryBackend` — the **read-only** query seam for the API server (4.2).
+ *
+ * This is deliberately distinct from {@link StoreBackend} (`src/store/backend.ts`),
+ * which is the central-collector **write/ingest** seam. The two seams have opposite
+ * shapes: ingest merges incoming deltas; this one answers topology questions. A
+ * non-SQLite backend (4.3) implements both. Keeping them separate means the API
+ * never gains a write path and the ingest core never gains a query path.
+ *
+ * Every method takes a {@link TenantContext}. Session resolution is tenant-scoped, so
+ * a caller bound to tenant A can never read tenant B's topology — even by naming a
+ * session id that belongs to B (it resolves to "not found", never B's data). This
+ * mirrors the MCP server's `resolveSession` tenant guard exactly.
+ */
+
+/** The tenant (org-scope) a request is bound to. `'local'` (DEFAULT_TENANT) until a real org is supplied. */
+interface TenantContext {
+    tenant: string;
+}
+interface NodeQuery {
+    search?: string;
+    types?: readonly string[];
+    limit?: number;
+    offset?: number;
+}
+interface DependencyQuery {
+    direction?: 'downstream' | 'upstream' | 'both';
+    maxDepth?: number;
+}
+interface NodesResult {
+    nodes: NodeRow[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface HealthResult {
+    store: 'sqlite';
+    sessions: number;
+}
+/** A requested resource (session / diff endpoint) does not exist for this tenant → REST 404. */
+declare class NotFoundError extends Error {
+    constructor(message: string);
+}
+/** Narrow, read-only view of the topology store. Tenant is required on every call. */
+interface QueryBackend {
+    /** Aggregate, low-token index of the resolved session. Throws {@link NotFoundError} if no session resolves. */
+    summary(ctx: TenantContext, sessionId?: string): GraphSummary;
+    /** Page/search nodes of the resolved session. Throws {@link NotFoundError} if no session resolves. */
+    nodes(ctx: TenantContext, q: NodeQuery, sessionId?: string): NodesResult;
+    /** One node by id (or `undefined` if absent). Throws {@link NotFoundError} if no session resolves. */
+    node(ctx: TenantContext, id: string, sessionId?: string): NodeRow | undefined;
+    /** Dependency traversal from a node. Throws {@link NotFoundError} if no session resolves. */
+    dependencies(ctx: TenantContext, id: string, q: DependencyQuery, sessionId?: string): TraversalResult;
+    /** Compare two sessions (both must belong to the tenant). Throws {@link NotFoundError} on an unknown/foreign id. */
+    diff(ctx: TenantContext, base: string, current: string): TopologyDiff;
+    /** All sessions for this tenant, newest first. */
+    sessions(ctx: TenantContext): SessionRow[];
+    /** Liveness/coverage probe (never resolves a session). */
+    health(ctx: TenantContext): HealthResult;
+}
+/**
+ * `QueryBackend` over the local `CartographyDB`. A thin read adapter: the schema,
+ * migrations, and SQL all live in `db.ts`; this only resolves the tenant-scoped
+ * session and forwards. Constructing it adds no state and no schema.
+ */
+declare class SqliteQueryBackend implements QueryBackend {
+    private readonly db;
+    private readonly defaultSession;
+    constructor(db: CartographyDB, defaultSession?: string | 'latest');
+    /**
+     * Resolve the session id for a request, scoped to `ctx.tenant`. An explicit id must
+     * belong to the tenant or it resolves to undefined (cross-tenant isolation); else the
+     * newest `discover` session for the tenant. Mirrors `resolveSession` in the MCP server.
+     */
+    private resolveSession;
+    summary(ctx: TenantContext, sessionId?: string): GraphSummary;
+    nodes(ctx: TenantContext, q: NodeQuery, sessionId?: string): NodesResult;
+    node(ctx: TenantContext, id: string, sessionId?: string): NodeRow | undefined;
+    dependencies(ctx: TenantContext, id: string, q: DependencyQuery, sessionId?: string): TraversalResult;
+    diff(ctx: TenantContext, base: string, current: string): TopologyDiff;
+    sessions(ctx: TenantContext): SessionRow[];
+    health(ctx: TenantContext): HealthResult;
+}
+/** Construct the default SQLite-backed read query backend. */
+declare function createSqliteQueryBackend(db: CartographyDB, defaultSession?: string | 'latest'): QueryBackend;
+
 /**
  * Global-identity merge core for the central collector (2.12) — pure, no I/O.
  *
@@ -1960,8 +2061,203 @@ interface HttpOptions {
         body: unknown;
     };
 }
+/**
+ * Start a Streamable HTTP server. A fresh MCP server instance is created per
+ * session via `factory`, so multiple clients can connect concurrently.
+ */
 declare function runHttp(factory: () => McpServer, opts?: HttpOptions): Promise<http.Server>;
 
+/**
+ * Shared HTTP auth + bind-hardening primitives.
+ *
+ * Extracted verbatim from `src/mcp/transports.ts` so the MCP transport, the REST/
+ * GraphQL API server (4.2), and any future HTTP surface consume **one** provably-
+ * identical implementation of the CVE-2025-66414 guards, the constant-time bearer
+ * compare, and the default Host allowlist. The allowlist — not any one caller — is
+ * the security boundary; centralizing it here keeps every networked surface on the
+ * same posture and makes the behavior unit-testable in isolation.
+ */
+/** Loopback hosts are safe to bind without an explicit Host allowlist. */
+declare const LOOPBACK_HOSTS: ReadonlySet<string>;
+/** True when `host` is a loopback address (safe to bind without an allowlist/token). */
+declare function isLoopbackHost(host: string): boolean;
+/** Constant-time comparison to avoid leaking the token via timing. */
+declare function timingSafeEqual(a: string, b: string): boolean;
+/**
+ * Extract the bearer token from an Authorization header, if present. Parsed with
+ * linear string ops (no regex) so a user-controlled header can never trigger
+ * polynomial backtracking (ReDoS) — `^Bearer\s+(.+)$` is ambiguous between `\s+`
+ * and `.+` on a long run of spaces.
+ */
+declare function bearerToken(header: string | undefined): string | undefined;
+/**
+ * Returns true if the request is authenticated: a request is authenticated when no
+ * token is configured (open loopback dev mode) OR the `Authorization: Bearer` value
+ * is present and constant-time-equal to the configured token. The caller maps a
+ * `false` to a 401.
+ */
+declare function checkBearer(authorizationHeader: string | undefined, token: string | undefined): boolean;
+interface BindGuardOptions {
+    host: string;
+    port: number;
+    allowedHosts?: string[];
+    token?: string;
+}
+/**
+ * Enforce the CVE-2025-66414 + mandatory-token guards before binding. Throws the
+ * exact errors `runHttp` raised inline, so existing transport behavior is preserved:
+ * a non-loopback bind requires BOTH an explicit `allowedHosts` allowlist AND a token.
+ */
+declare function assertSafeBind(opts: BindGuardOptions): void;
+/** Default Host allowlist: the bound host plus the localhost variants, all `:port`. */
+declare function defaultAllowedHosts(host: string, port: number): string[];
+
+/**
+ * Per-request tenant resolution for the API server (4.2).
+ *
+ * The tenant (org-scope) is a first-class request property: it is resolved once,
+ * up front, and threaded into every {@link QueryBackend} call so isolation is
+ * structural, not bolted on. A request may name a tenant via the
+ * `X-Cartograph-Tenant` header or a `?tenant=` query param; absent either, it
+ * defaults to the server's configured default (normally `DEFAULT_TENANT='local'`).
+ *
+ * Validation reuses `normalizeTenant` (the single charset-allowlisted validator,
+ * `^[\w.@:+-]{1,128}$`) — but here we **reject** a malformed value with a typed
+ * error (→ HTTP 400) rather than silently falling back, so a client never believes
+ * it is scoped to one tenant while being served another. The raw input is never
+ * reflected into a response.
+ */
+
+declare const TENANT_HEADER = "x-cartograph-tenant";
+/** The supplied tenant value did not pass the charset/length allowlist → HTTP 400. */
+declare class InvalidTenantError extends Error {
+    constructor();
+}
+interface TenantOptions {
+    /** Default tenant when the request names none. Defaults to `DEFAULT_TENANT` ('local'). */
+    defaultTenant?: string;
+    /** Header to read the tenant from. Defaults to `x-cartograph-tenant`. */
+    header?: string;
+}
+/**
+ * Resolve the tenant from the request header or `?tenant=` query param, else the
+ * configured default. A supplied-but-malformed value throws {@link InvalidTenantError}
+ * (the caller maps it to a 400) instead of silently defaulting.
+ */
+declare function resolveTenant(req: IncomingMessage, url: URL, opts?: TenantOptions): TenantContext;
+
+/**
+ * The read-only API HTTP server (4.2), on Node's built-in `http` (zero new runtime dep).
+ *
+ * Request flow mirrors the MCP transport (`src/mcp/transports.ts`): the CVE-2025-66414
+ * bind guards run at startup (shared `assertSafeBind`); per request the Host header is
+ * checked against the allowlist (DNS-rebinding), then the bearer token is verified
+ * **before any backend access**, then the tenant is resolved, then the route dispatches.
+ * REST handlers are pure (`rest.ts`); GraphQL is wired when enabled (`graphql.ts`). One
+ * structured stderr access line per request — never the token, never query values.
+ */
+
+interface ApiServerOptions extends BindGuardOptions {
+    backend: QueryBackend;
+    version: string;
+    /** CORS Origin allowlist. Default: none (same-origin only). */
+    allowedOrigins?: string[];
+    /** Tenant resolution options (header name / default tenant). */
+    tenant?: TenantOptions;
+    /** Expose `/graphql` (default true). */
+    graphql?: boolean;
+    /** Access logger (stderr). */
+    log?: (msg: string) => void;
+}
+/** Start the read-only API server. Resolves once it is listening. */
+declare function runApi(opts: ApiServerOptions): Promise<http.Server>;
+
+/**
+ * OpenAPI 3.1 document generation for the read-only API (4.2).
+ *
+ * The document is **generated from the zod response schemas** (`schemas.ts`), never
+ * hand-maintained, so it cannot drift from what the server actually returns. A
+ * committed copy lives at `docs/api/openapi.json`; a test asserts the built document
+ * deep-equals it (drift guard) and validates under `ajv`.
+ *
+ * `zodToJsonSchema` is a small, fail-closed projection covering exactly the zod
+ * constructs `schemas.ts` uses (object/array/string/number/integer/boolean/enum/
+ * literal/record/optional). An unsupported construct throws, so a future schema
+ * change can't be silently mis-projected. (The provider tool layer has its own flat
+ * converter in `src/providers/zod-schema.ts`; this one is recursive and serves the
+ * API's nested response shapes.)
+ */
+
+/** Project a zod schema to a JSON-Schema (2020-12) fragment. Fail-closed on the unknown. */
+declare function zodToJsonSchema(schema: z.ZodTypeAny): Record<string, unknown>;
+interface OpenApiOptions {
+    version: string;
+}
+/** Build the OpenAPI 3.1 document from the zod schemas + the static route table. Deterministic. */
+declare function buildOpenApiDocument(opts: OpenApiOptions): Record<string, unknown>;
+
+/**
+ * Hand-rolled, zero-dependency GraphQL layer for the read-only API (4.2).
+ *
+ * Mirrors REST over `POST /graphql` (and serves the SDL on `GET /graphql`) without
+ * adding a `graphql`/`apollo` runtime dependency. Resolvers delegate to the same
+ * {@link QueryBackend} and reuse the REST projections (`rest.ts`), so REST and GraphQL
+ * return byte-identical shapes and the consent posture stays in one place. It is
+ * strictly **read-only**: there is no `Mutation` type and a `mutation` document is
+ * rejected. A small tokenizer/parser handles the query subset the schema needs
+ * (fields, arguments, variables, nested selections) and a minimal `__schema`
+ * introspection response keeps GraphiQL-style clients working.
+ */
+
+interface GraphqlDeps {
+    backend: QueryBackend;
+}
+interface GraphqlResult {
+    data?: unknown;
+    errors?: Array<{
+        message: string;
+    }>;
+}
+declare const SDL = "# Cartograph read-only GraphQL API (4.2). Mirrors the REST surface.\nschema { query: Query }\n\ntype Query {\n  summary(session: String): Summary\n  nodes(search: String, types: [String!], limit: Int, offset: Int, session: String): NodeConnection\n  node(id: String!, session: String): Node\n  dependencies(id: String!, direction: Direction, maxDepth: Int, session: String): Dependencies\n  diff(base: String!, current: String!): Diff\n  sessions: [Session!]!\n}\n\nenum Direction { downstream upstream both }\n\ntype Totals { nodes: Int! edges: Int! }\ntype Count { key: String! value: Int! }\ntype TopConnected { id: String! name: String! type: String! degree: Int! }\ntype Anomaly { nodeId: String! kind: String! severity: String! reason: String! }\ntype Cost { amount: Float! currency: String! period: String! source: String }\ntype CostRollup { key: String! currency: String! period: String! total: Float! nodes: Int! }\ntype CostCoverage { withCost: Int! total: Int! }\n\ntype Node {\n  id: String! type: String! name: String! confidence: Float!\n  domain: String subDomain: String qualityScore: Float owner: String cost: Cost tags: [String!]!\n}\ntype DependencyNode {\n  id: String! type: String! name: String! confidence: Float!\n  domain: String subDomain: String qualityScore: Float owner: String cost: Cost tags: [String!]! depth: Int!\n}\ntype Edge { sourceId: String! targetId: String! relationship: String! confidence: Float! evidence: String! }\n\ntype Summary {\n  sessionId: String!\n  totals: Totals!\n  topConnected: [TopConnected!]!\n  anomalies: [Anomaly!]!\n  contributors: Int!\n  costByDomain: [CostRollup!]!\n  costByOwner: [CostRollup!]!\n  costCoverage: CostCoverage!\n}\n\ntype NodeConnection { nodes: [Node!]! total: Int! limit: Int! offset: Int! }\ntype Dependencies { root: Node direction: Direction! maxDepth: Int! nodes: [DependencyNode!]! edges: [Edge!]! }\n\ntype SessionEndpoint { sessionId: String! startedAt: String! nodeCount: Int! edgeCount: Int! }\ntype DiffSummary { nodesAdded: Int! nodesRemoved: Int! nodesChanged: Int! edgesAdded: Int! edgesRemoved: Int! }\ntype NodeChange { id: String! changedFields: [String!]! confidenceDelta: Float! }\ntype DiffNodes { added: [Node!]! removed: [Node!]! changed: [NodeChange!]! unchanged: Int! }\ntype DiffEdges { added: [Edge!]! removed: [Edge!]! unchanged: Int! }\ntype DiffAnomalies { added: [Anomaly!]! }\ntype Diff {\n  base: SessionEndpoint! current: SessionEndpoint! summary: DiffSummary!\n  nodes: DiffNodes! edges: DiffEdges! anomalies: DiffAnomalies!\n}\n\ntype Session { id: String! mode: String! startedAt: String! completedAt: String name: String tenant: String! lastScannedAt: String }\n";
+/** Execute a `{ query, variables, operationName }` request. Read-only; rejects mutations. */
+declare function executeGraphql(ctx: TenantContext, body: unknown, deps: GraphqlDeps): Promise<GraphqlResult>;
+/** `GET /graphql` → the SDL as text/plain. */
+declare function handleGraphqlGet(): {
+    status: number;
+    body: string;
+};
+
+/**
+ * Shared entry logic for the read-only API server (4.2), used by both the dedicated
+ * `cartography-api` binary and the `api` CLI sub-command. Mirrors `src/mcp/start.ts`:
+ * opens the catalog, builds the SQLite query backend, resolves the bearer token from
+ * `--token`/`CARTOGRAPHY_HTTP_TOKEN`, and starts `runApi`. All logging is to stderr;
+ * the token value is never logged (only whether one is set).
+ */
+
+interface StartApiOptions {
+    dbPath?: string;
+    session?: string | 'latest';
+    port?: number;
+    host?: string;
+    allowedHosts?: string[];
+    allowedOrigins?: string[];
+    token?: string;
+    /** Expose `/graphql` (default true). */
+    graphql?: boolean;
+    /** Default tenant served when a request names none. */
+    tenant?: string;
+    log?: (msg: string) => void;
+}
+interface ParsedApiArgs extends StartApiOptions {
+    /** `--help`/`-h` was passed; the caller should print usage and exit 0. */
+    help?: boolean;
+}
+/** Parse `cartography-api` argv into StartApiOptions (unit-testable, no side effects). */
+declare function parseApiArgs(argv: string[]): ParsedApiArgs;
+/** Open the catalog, build the read backend, and start the API server. Returns the server. */
+declare function startApi(opts?: StartApiOptions): Promise<Server>;
+
 declare const installedAppsScanner: Scanner;
 
 /** Well-known listening ports → node type + service name. */
@@ -2559,7 +2855,12 @@ declare const SCAN_ARG_PATTERNS: {
 type ScanArgKind = keyof typeof SCAN_ARG_PATTERNS;
 /** Throw if `value` fails the strict pattern for `kind`; otherwise return it. */
 declare function assertSafeScanArg(kind: ScanArgKind, value: string): string;
-/** Redact `user:password@` credentials embedded in any URL/DSN-like string. */
+/**
+ * Redact `user:password@` credentials embedded in any URL/DSN-like string. The
+ * quantifiers are length-bounded (schemes <64, userinfo/password <256 chars — far
+ * beyond any real DSN) so the pattern is linear and cannot polynomially backtrack
+ * (ReDoS) on adversarial input like `aaaa…` with no `://`.
+ */
 declare function redactSecrets(value: string): string;
 /** Recursively redact secrets from arbitrary metadata before persistence. */
 declare function redactValue(value: unknown): unknown;
@@ -2988,6 +3289,42 @@ interface WebhookSinkOptions {
     token?: string;
     timeoutMs?: number;
 }
+/** Injectable fetch (defaults to the global) — lets tests deliver without a socket. */
+type FetchLike = (url: string, init: RequestInit) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+interface PostJsonOptions {
+    url: string;
+    body: unknown;
+    /** Extra request headers (e.g. provider auth). `content-type: application/json` is always set. */
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    /** Sink name for structured logs (never logs the url/token/body). */
+    sinkName: string;
+    /** Injected fetch for tests; defaults to the global. */
+    fetchImpl?: FetchLike;
+}
+/**
+ * Shared outbound JSON POST carrying the load-bearing sink hardening, reused by
+ * {@link WebhookSink} and the Slack/PagerDuty/Jira provider sinks so there is exactly
+ * one egress code path:
+ *  - refuses a non-`https:` / non-loopback target ({@link isSecureWebhookUrl}, SSRF/plaintext guard);
+ *  - `AbortSignal.timeout` bounded;
+ *  - **never throws** for a transient failure (logs and resolves so the runner continues);
+ *  - logs only `stripSensitive(url)` (host:port) — never the full url, headers, token, or body.
+ * The body must already be redaction-safe (callers pass `redactValue(...)` output or a
+ * provider payload derived from it).
+ */
+declare function postJson(opts: PostJsonOptions): Promise<void>;
+/**
+ * True if `url` is safe to POST to: `https:`, or `http:` only to a loopback host,
+ * or any scheme when the documented `CARTOGRAPHY_ALLOW_INSECURE_SYNC=1` escape
+ * hatch (test-only) is set. An unparseable URL is treated as insecure. Mirrors the
+ * 2.11 `pushDeltas` guard so the drift feature never silently exfiltrates over the
+ * wire in plaintext.
+ */
+declare function isSecureWebhookUrl(url: string, env?: NodeJS.ProcessEnv): boolean;
 /**
  * Outbound sink: POSTs the alert as JSON to an operator-configured endpoint. The
  * first and only outbound network surface of the drift feature — off by default
@@ -3009,11 +3346,114 @@ declare class WebhookSink implements DriftSink {
     emit(alert: DriftAlert): Promise<void>;
 }
 
+/**
+ * Provider drift sinks (4.4): Slack / PagerDuty / Jira. Each is a thin {@link DriftSink}
+ * that (1) redacts the alert (`redactValue`), (2) maps it to the provider payload via the
+ * pure adapters in `providers.ts`, and (3) delivers it through the shared {@link postJson}
+ * helper — inheriting the *exact* `WebhookSink` hardening (https-or-loopback SSRF guard,
+ * bounded timeout, never-throw, `stripSensitive` log-only). They differ only in where the
+ * provider places its secret: Slack in the URL, PagerDuty as a `routing_key` in the body,
+ * Jira as an `Authorization: Basic` header.
+ */
+
+/** Default PagerDuty Events API v2 ingest endpoint. */
+declare const PAGERDUTY_ENQUEUE_URL = "https://events.pagerduty.com/v2/enqueue";
+interface BaseSinkOptions {
+    url: string;
+    timeoutMs?: number;
+    /** Injected fetch for tests; defaults to the global. */
+    fetchImpl?: FetchLike;
+}
+/** Slack incoming webhook. The configured `url` is the secret; no auth header is sent. */
+declare class SlackSink implements DriftSink {
+    private readonly opts;
+    readonly name = "slack";
+    constructor(opts: BaseSinkOptions);
+    emit(alert: DriftAlert): Promise<void>;
+}
+interface PagerDutySinkOptions extends BaseSinkOptions {
+    /** Events API v2 routing key (rides in the body, PagerDuty's auth model). */
+    routingKey: string;
+}
+/** PagerDuty Events API v2 `trigger`. `url` defaults to {@link PAGERDUTY_ENQUEUE_URL}. */
+declare class PagerDutySink implements DriftSink {
+    private readonly opts;
+    readonly name = "pagerduty";
+    constructor(opts: PagerDutySinkOptions);
+    emit(alert: DriftAlert): Promise<void>;
+}
+interface JiraSinkOptions extends BaseSinkOptions {
+    /** Jira account email (basic-auth user). */
+    email: string;
+    /** Jira API token (basic-auth pass). */
+    token: string;
+    /** Target project key (e.g. "OPS"). */
+    project: string;
+    /** Issue type name (default "Task"). */
+    issueType?: string;
+}
+/** Jira REST API v2 create-issue, authenticated with `Authorization: Basic base64(email:token)`. */
+declare class JiraSink implements DriftSink {
+    private readonly opts;
+    readonly name = "jira";
+    constructor(opts: JiraSinkOptions);
+    emit(alert: DriftAlert): Promise<void>;
+}
+
+/**
+ * Pure provider payload mappers (4.4): a classified {@link DriftAlert} → the JSON
+ * shape Slack / PagerDuty / Jira each expect. Deterministic, no I/O, no secrets —
+ * they operate on the **already-`redactValue`'d** alert the sinks pass in, and read
+ * only structured fields (severity/counts/item refs), never raw node metadata. The
+ * delivery + auth + SSRF hardening lives in `provider-sink.ts`/`webhook.ts`; these
+ * are just shape transforms, so they are trivially snapshot-testable.
+ */
+
+interface SlackMessage {
+    text: string;
+    blocks: unknown[];
+}
+/** Map an alert to a Slack incoming-webhook message (Block Kit). The webhook URL is the secret. */
+declare function formatSlack(alert: DriftAlert): SlackMessage;
+interface PagerDutyEvent {
+    routing_key: string;
+    event_action: 'trigger';
+    dedup_key: string;
+    payload: {
+        summary: string;
+        source: string;
+        severity: 'info' | 'warning' | 'critical';
+        timestamp: string;
+        custom_details: Record<string, unknown>;
+    };
+}
+/** Map an alert to a PagerDuty Events API v2 `trigger`. `routingKey` rides in the body (PD's auth model). */
+declare function formatPagerDuty(alert: DriftAlert, routingKey: string): PagerDutyEvent;
+interface JiraIssue {
+    fields: {
+        project: {
+            key: string;
+        };
+        issuetype: {
+            name: string;
+        };
+        summary: string;
+        description: string;
+    };
+}
+interface JiraOptions {
+    project: string;
+    issueType?: string;
+}
+/** Map an alert to a Jira create-issue body. Auth (Basic email:token) is applied by the sink, not here. */
+declare function formatJira(alert: DriftAlert, opts: JiraOptions): JiraIssue;
+
 /**
  * Construct sinks from config. Absent/empty config → `[new StdoutSink()]` (the
- * local default). A webhook sink's token falls back to `CARTOGRAPHY_DRIFT_TOKEN`
- * when not given explicitly (mirroring `CARTOGRAPHY_HTTP_TOKEN`). A webhook entry
- * without a url is skipped defensively (the schema already rejects it).
+ * local default). Secrets (webhook `token`, Jira token, PagerDuty routing key) fall
+ * back to `CARTOGRAPHY_DRIFT_TOKEN` when not given explicitly (mirroring
+ * `CARTOGRAPHY_HTTP_TOKEN`). A provider entry missing a required field is skipped
+ * with a warning rather than aborting the others — graceful degradation.
  */
 declare function buildSinks(drift?: DriftConfig): DriftSink[];
 
@@ -3429,4 +3869,4 @@ declare function logInfo(message: string, context?: Record<string, unknown>): vo
 declare function logWarn(message: string, context?: Record<string, unknown>): void;
 declare function logError(message: string, context?: Record<string, unknown>): void;
 
-export { ANOMALY_KINDS, ANOMALY_SEVERITIES, type AgentProvider, type AgentRunContext, type AgentTool, type Anomaly, type AnomalyConfig, type AnomalyKind, type AnomalySeverity, type AnomalyThresholds, type AnonViolation, type AnonymizationLevel, type AskUserFn, CLIENTS, CONFIDENCE, COST_PERIODS, type CartographyConfig, CartographyDB, type CartographyMapData, type CentralDbConfig, CentralDbConfigSchema, type ClassifiedItem, type ClassifyInput, type ClassifyResult, type ClientSpec, type Cluster, ClusterSchema, type ComplianceInput, type ComplianceReport, ComplianceReportSchema, type ComplianceRule, ComplianceRuleSchema, type Condition, ConditionSchema, ConfigError, type ConfigFile, ConfigFileSchema, type ConfigFormat, type Connection, ConnectionSchema, type Contributor, type ControlResult, ControlResultSchema, type CostEntry, CostEntrySchema, type CostPeriod, type CostRecord, type CostSource, type CreateMcpServerOptions, type CronFields, CsvCostSource, type CsvCostSourceOptions, DEFAULT_ANOMALY_THRESHOLDS, DEFAULT_FAST_MODEL, DEFAULT_LEAD_MODEL, DEFAULT_SERVER_NAME, DEFAULT_TENANT, DOMAIN_COLORS, DOMAIN_PALETTE, DRIFT_FIELDS, type DataAsset, DataAssetSchema, type DiscoveryEdge, type DiscoveryEvent, type DiscoveryFn, type DiscoveryNode, type DriftAlert, type DriftAlertItem, type DriftConfig, DriftConfigSchema, type DriftField, type DriftItemKind, type DriftRunRow, type DriftSink, type DriftSinkConfig, EDGE_RELATIONSHIPS, type EdgeRelationship, type EdgeRow, EdgeSchema, type EmbeddingProvider, type EnrichResult, type EntryOptions, type EstablishedConn, type EvidenceKind, type FragmentKind, type GraphSummary, type HttpOptions, INGEST_SCHEMA_VERSION, type IngestEnvelope, IngestEnvelopeSchema, type IngestHandler, type IngestOptions, type IngestResponse, type IngestResult, type InstallPlan, type LocalDiscoveryOptions, type LocalDiscoveryResult, type LogEntry, type LogLevel, MCP_BIN, type MatchStrategy, NODE_TYPES, NODE_TYPE_GROUPS, type NlIntent, type NlQueryOptions, type NlQueryResult, type NlRelation, type NodeAttribution, type NodeChange, type NodeIdentity, type NodeRow, NodeSchema, type NodeType, OUTPUT_FORMATS, type OrgKeyOptions, type OrgSummary, type OsKind, type OutputFormat, PACKAGE_NAME, PENDING_STATUSES, PERSONAL, PORT_MAP, PRIVATE_IP, PUSH_SCHEMA_VERSION, type PendingShareRow, type PendingStatus, type PlanOptions, type PolicyResult, type ProviderFactory, type ProviderName, ProviderRegistry, type PushItem, type PushOptions, type PushResult, RELATION_TO_DIRECTION, type ResolveContext, type RuleCheck, RuleCheckSchema, type RuleScope, type Ruleset, RulesetSchema, type RunDriftOptions, SCAN_ARG_PATTERNS, SECURITY_METADATA_KEYS, SEVERITIES, SEVERITY_WEIGHT, SHARING_LEVELS, type ScanArgKind, type ScanContext, type ScanHintParams, type ScanResult, type Scanner, type ScannerPlugin, type ScannerPluginApi, ScannerRegistry, ScannerShape, type ScheduleConfig, ScheduleConfigSchema, type ScheduledRunResult, type Scope, type SearchFn, type SemanticSearchOptions, type ServerEntry, type SessionRow, type Severity, type SharePreview, type SharePreviewEntry, type SharingLevel, SharingLevelSchema, type SharingPolicy, type ShellKind, SqliteStoreBackend, StdoutSink, type StoreBackend, type SyncClassifyOptions, type SyncClassifyResult, type ToolResult, type TopologyDelta, type TopologyDiff, type TopologyInput, type TraversalResult, VectorStore, WebhookSink, type WebhookSinkOptions, applyInstall, applySharingLevel, assertReadOnly, assertSafeScanArg, assignColors, bookmarksScanner, buildCartographyToolHandlers, buildMapData, buildReport, buildSinks, centralDbFromEnv, checkPrerequisites, checkReadOnly, clampText, classify, classifyDrift, cleanupTempFiles, cloudAwsScanner, cloudAzureScanner, cloudGcpScanner, codeAddMcpCommand, computeCentroid, computeClusterBounds, computeIdentity, connectionsScanner, contentHash, createBashTool, createCartographyTools, createClaudeProvider, createDefaultRegistry, createHashEmbedder, createIngestHandler, createLocalEmbedder, createMcpServer, createOllamaProvider, createOpenAIProvider, createScanRunner, createSemanticSearch, currentOs, cursorDeeplink, databasesScanner, deepMerge, defaultConfig, defaultContext, defaultProviderRegistry, defaultRegistry, defaultServerEntry, definePlugin, deriveSessionName, detectAnomalies, detectOrphans, detectShadowIt, diffTopology, edgesToConnections, enrichCosts, evaluateCheck, evaluateRule, evidenceLine, executeNlQuery, exportAll, exportBackstageYAML, exportComplianceReport, exportCostCSV, exportCostSummary, exportDiscoveryApp, exportJGF, exportJSON, extractListeningPorts, filterBySeverity, findAnonViolations, formatComplianceText, generateDependencyMermaid, generateDiffMermaid, generateTopologyMermaid, getClient, getRuleset, globalId, groupByDomain, hexCorners, hexDistance, hexNeighbors, hexRing, hexSpiral, hexToPixel, hmacKey, hostname, ingestEnvelope, installedAppsScanner, isPersonalHost, isReadOnlyCommand, isRemembered, k8sScanner, keyMetaOf, layoutClusters, listClients, listRulesets, loadConfig, loadOrgKey, loadPlugins, loadRuleset, localDiscoveryFn, log, logDebug, logError, logInfo, logWarn, machineId, maxSeverity, mcpServerObject, newAnomalies, nextRun, nodesToAssets, normalizeId, normalizeTenant, orgKeyPath, osUser, parseComposeDeps, parseConfig, parseConnectionString, parseCostCsv, parseCron, parseEstablished, parseNginxUpstreams, parseNlQuery, parseScanHint, pixelToHex, planInstall, portsScanner, previewShare, pseudonymize, pseudonymizeFragment, pseudonymizeString, pushDeltas, readConfigFile, redactConnectionString, redactSecrets, redactValue, renderDiff, resolveEffectiveLevel, resolveNlQuery, resolveSharingLevel, revalidateAnonymized, reversalKey, reversePseudonym, rotateOrgKey, runDiscovery, runDrift, runHttp, runLocalDiscovery, runOnce, runStdio, runSyncClassify, safeEnv, safeJson, safetyHook, sanitizeUntrusted, sanitizeValue, scoreTopology, securityRelevantChange, serializeConfig, serviceConfigScanner, setVerbose, shadeVariant, shapeToJsonSchema, shareHash, splitSegments, stableStringify, stripSensitive, validateScanner, vscodeDeeplink };
+export { ANOMALY_KINDS, ANOMALY_SEVERITIES, type AgentProvider, type AgentRunContext, type AgentTool, type Anomaly, type AnomalyConfig, type AnomalyKind, type AnomalySeverity, type AnomalyThresholds, type AnonViolation, type AnonymizationLevel, type ApiServerOptions, type AskUserFn, type BindGuardOptions, CLIENTS, CONFIDENCE, COST_PERIODS, type CartographyConfig, CartographyDB, type CartographyMapData, type CentralDbConfig, CentralDbConfigSchema, type ClassifiedItem, type ClassifyInput, type ClassifyResult, type ClientSpec, type Cluster, ClusterSchema, type ComplianceInput, type ComplianceReport, ComplianceReportSchema, type ComplianceRule, ComplianceRuleSchema, type Condition, ConditionSchema, ConfigError, type ConfigFile, ConfigFileSchema, type ConfigFormat, type Connection, ConnectionSchema, type Contributor, type ControlResult, ControlResultSchema, type CostEntry, CostEntrySchema, type CostPeriod, type CostRecord, type CostSource, type CreateMcpServerOptions, type CronFields, CsvCostSource, type CsvCostSourceOptions, DEFAULT_ANOMALY_THRESHOLDS, DEFAULT_FAST_MODEL, DEFAULT_LEAD_MODEL, DEFAULT_SERVER_NAME, DEFAULT_TENANT, DOMAIN_COLORS, DOMAIN_PALETTE, DRIFT_FIELDS, type DataAsset, DataAssetSchema, type DependencyQuery, type DiscoveryEdge, type DiscoveryEvent, type DiscoveryFn, type DiscoveryNode, type DriftAlert, type DriftAlertItem, type DriftConfig, DriftConfigSchema, type DriftField, type DriftItemKind, type DriftRunRow, type DriftSink, type DriftSinkConfig, EDGE_RELATIONSHIPS, type EdgeRelationship, type EdgeRow, EdgeSchema, type EmbeddingProvider, type EnrichResult, type EntryOptions, type EstablishedConn, type EvidenceKind, type FetchLike, type FragmentKind, type GraphSummary, type HealthResult, type HttpOptions, INGEST_SCHEMA_VERSION, type IngestEnvelope, IngestEnvelopeSchema, type IngestHandler, type IngestOptions, type IngestResponse, type IngestResult, type InstallPlan, InvalidTenantError, type JiraIssue, type JiraOptions, JiraSink, type JiraSinkOptions, LOOPBACK_HOSTS, type LocalDiscoveryOptions, type LocalDiscoveryResult, type LogEntry, type LogLevel, MCP_BIN, type MatchStrategy, NODE_TYPES, NODE_TYPE_GROUPS, type NlIntent, type NlQueryOptions, type NlQueryResult, type NlRelation, type NodeAttribution, type NodeChange, type NodeIdentity, type NodeQuery, type NodeRow, NodeSchema, type NodeType, type NodesResult, NotFoundError, OUTPUT_FORMATS, type OrgKeyOptions, type OrgSummary, type OsKind, type OutputFormat, PACKAGE_NAME, PAGERDUTY_ENQUEUE_URL, PENDING_STATUSES, PERSONAL, PORT_MAP, PRIVATE_IP, PUSH_SCHEMA_VERSION, type PagerDutyEvent, PagerDutySink, type PagerDutySinkOptions, type ParsedApiArgs, type PendingShareRow, type PendingStatus, type PlanOptions, type PolicyResult, type PostJsonOptions, type ProviderFactory, type ProviderName, ProviderRegistry, type PushItem, type PushOptions, type PushResult, type QueryBackend, RELATION_TO_DIRECTION, type ResolveContext, type RuleCheck, RuleCheckSchema, type RuleScope, type Ruleset, RulesetSchema, type RunDriftOptions, SCAN_ARG_PATTERNS, SDL, SECURITY_METADATA_KEYS, SEVERITIES, SEVERITY_WEIGHT, SHARING_LEVELS, type ScanArgKind, type ScanContext, type ScanHintParams, type ScanResult, type Scanner, type ScannerPlugin, type ScannerPluginApi, ScannerRegistry, ScannerShape, type ScheduleConfig, ScheduleConfigSchema, type ScheduledRunResult, type Scope, type SearchFn, type SemanticSearchOptions, type ServerEntry, type SessionRow, type Severity, type SharePreview, type SharePreviewEntry, type SharingLevel, SharingLevelSchema, type SharingPolicy, type ShellKind, type SlackMessage, SlackSink, SqliteQueryBackend, SqliteStoreBackend, type StartApiOptions, StdoutSink, type StoreBackend, type SyncClassifyOptions, type SyncClassifyResult, TENANT_HEADER, type TenantContext, type TenantOptions, type ToolResult, type TopologyDelta, type TopologyDiff, type TopologyInput, type TraversalResult, VectorStore, WebhookSink, type WebhookSinkOptions, applyInstall, applySharingLevel, assertReadOnly, assertSafeBind, assertSafeScanArg, assignColors, bearerToken, bookmarksScanner, buildCartographyToolHandlers, buildMapData, buildOpenApiDocument, buildReport, buildSinks, centralDbFromEnv, checkBearer, checkPrerequisites, checkReadOnly, clampText, classify, classifyDrift, cleanupTempFiles, cloudAwsScanner, cloudAzureScanner, cloudGcpScanner, codeAddMcpCommand, computeCentroid, computeClusterBounds, computeIdentity, connectionsScanner, contentHash, createBashTool, createCartographyTools, createClaudeProvider, createDefaultRegistry, createHashEmbedder, createIngestHandler, createLocalEmbedder, createMcpServer, createOllamaProvider, createOpenAIProvider, createScanRunner, createSemanticSearch, createSqliteQueryBackend, currentOs, cursorDeeplink, databasesScanner, deepMerge, defaultAllowedHosts, defaultConfig, defaultContext, defaultProviderRegistry, defaultRegistry, defaultServerEntry, definePlugin, deriveSessionName, detectAnomalies, detectOrphans, detectShadowIt, diffTopology, edgesToConnections, enrichCosts, evaluateCheck, evaluateRule, evidenceLine, executeGraphql, executeNlQuery, exportAll, exportBackstageYAML, exportComplianceReport, exportCostCSV, exportCostSummary, exportDiscoveryApp, exportJGF, exportJSON, extractListeningPorts, filterBySeverity, findAnonViolations, formatComplianceText, formatJira, formatPagerDuty, formatSlack, generateDependencyMermaid, generateDiffMermaid, generateTopologyMermaid, getClient, getRuleset, globalId, groupByDomain, handleGraphqlGet, hexCorners, hexDistance, hexNeighbors, hexRing, hexSpiral, hexToPixel, hmacKey, hostname, ingestEnvelope, installedAppsScanner, isLoopbackHost, isPersonalHost, isReadOnlyCommand, isRemembered, isSecureWebhookUrl, k8sScanner, keyMetaOf, layoutClusters, listClients, listRulesets, loadConfig, loadOrgKey, loadPlugins, loadRuleset, localDiscoveryFn, log, logDebug, logError, logInfo, logWarn, machineId, maxSeverity, mcpServerObject, newAnomalies, nextRun, nodesToAssets, normalizeId, normalizeTenant, orgKeyPath, osUser, parseApiArgs, parseComposeDeps, parseConfig, parseConnectionString, parseCostCsv, parseCron, parseEstablished, parseNginxUpstreams, parseNlQuery, parseScanHint, pixelToHex, planInstall, portsScanner, postJson, previewShare, pseudonymize, pseudonymizeFragment, pseudonymizeString, pushDeltas, readConfigFile, redactConnectionString, redactSecrets, redactValue, renderDiff, resolveEffectiveLevel, resolveNlQuery, resolveSharingLevel, resolveTenant, revalidateAnonymized, reversalKey, reversePseudonym, rotateOrgKey, runApi, runDiscovery, runDrift, runHttp, runLocalDiscovery, runOnce, runStdio, runSyncClassify, safeEnv, safeJson, safetyHook, sanitizeUntrusted, sanitizeValue, scoreTopology, securityRelevantChange, serializeConfig, serviceConfigScanner, setVerbose, shadeVariant, shapeToJsonSchema, shareHash, splitSegments, stableStringify, startApi, stripSensitive, timingSafeEqual, validateScanner, vscodeDeeplink, zodToJsonSchema };