@ggui-ai/mcp-server 0.1.0-rc.1

package/dist/reserved-validators.js

@@ -0,0 +1,101 @@
+/**
+ * Reserved-channel payload validator composition for `@ggui-ai/mcp-server`.
+ *
+ * `@ggui-ai/protocol` ships zero knowledge of A2UI (see Protocol #6,
+ * vendor-neutral separation). The preview channel's payload shape is
+ * authored in `@ggui-ai/preview-a2ui`; this module adapts that package's
+ * `parseServerMessage` into the
+ * {@link ReservedChannelValidator} shape `validateStreamData` expects
+ * via its `extraReservedValidators` injection point.
+ *
+ * Composition surface:
+ *
+ *   - {@link composePreviewReservedValidator} — returns a single-entry
+ *     map binding `_ggui:preview` to the A2UI adapter. Call at server
+ *     construction and feed into `extraReservedValidators` on
+ *     `SessionChannelOptions` / `CreateGguiServerOptions`.
+ *   - {@link mergeReservedValidators} — combine multiple validator maps
+ *     when a caller provides their own extras AND the server wants to
+ *     layer A2UI on top. Caller-provided entries win on key conflict.
+ *
+ * Design note: kept deliberately narrow. No server-opinionated default
+ * catalog filtering, no surface-id checking — those live in the A2UI
+ * runtime consumer. The adapter enforces only what `parseServerMessage`
+ * enforces: message-shape conformance to the V1 write-path union.
+ */
+import { parseServerMessage, } from '@ggui-ai/preview-a2ui';
+import { PREVIEW_CHANNEL, } from '@ggui-ai/protocol';
+/**
+ * Adapter mapping `parseServerMessage` output to the
+ * `ValidationResult` shape `validateStreamData` returns. Accepts any
+ * `_ggui:preview` payload and surfaces the A2UI parse issues under the
+ * `payload` field path when rejection fires.
+ *
+ * Channel-close sentinel: `null` / `undefined` payloads on
+ * `_ggui:preview` are the live-channel terminal envelope emitted by the
+ * preview runner's `finalizePreviewChannel` (alongside
+ * `complete: true`). This is a transport-level teardown marker, NOT an
+ * A2UI message, so the A2UI adapter accepts it verbatim. Any
+ * non-null, non-undefined payload runs through the full A2UI validator.
+ */
+function a2uiPreviewValidator(payload) {
+    // Live-channel teardown sentinel — see JSDoc above.
+    if (payload === null || payload === undefined) {
+        return { valid: true, violations: [] };
+    }
+    const parsed = parseServerMessage(payload);
+    if (parsed.ok)
+        return { valid: true, violations: [] };
+    const violations = parsed.issues.map((issue) => ({
+        field: issue.path.length === 0 ? 'payload' : `payload.${issue.path.join('.')}`,
+        message: issue.message,
+        expected: 'A2UI ServerMessage (v0.9 write-path union)',
+        received: 'malformed',
+    }));
+    // If Zod produced no issues (defensive — safe-parse always surfaces
+    // at least one on failure), synthesize a single catch-all violation
+    // so callers still see a rejection reason.
+    if (violations.length === 0) {
+        violations.push({
+            field: 'payload',
+            message: 'A2UI preview payload did not match the V1 write-path union',
+            expected: 'A2UI ServerMessage (v0.9)',
+            received: 'malformed',
+        });
+    }
+    return { valid: false, violations };
+}
+/**
+ * Returns a reserved-validator map binding `_ggui:preview` to the A2UI
+ * adapter. Single-entry by design — each reserved channel gets its own
+ * validator; consumers that want to compose more should call
+ * {@link mergeReservedValidators}.
+ *
+ * No parameters today. When the A2UI V1 subset widens (e.g.
+ * `updateDataModel`), the adapter follows `parseServerMessage` without
+ * touching this export.
+ */
+export function composePreviewReservedValidator() {
+    return new Map([[PREVIEW_CHANNEL, a2uiPreviewValidator]]);
+}
+/**
+ * Merge two reserved-validator maps into one. Keys present in
+ * `override` WIN on conflict — the pattern is "server supplies
+ * defaults (A2UI), caller may replace by key".
+ *
+ * Returns a `ReadonlyMap` so the composed result has the same
+ * immutability guarantee as the individual inputs.
+ */
+export function mergeReservedValidators(base, override) {
+    if (!base && !override)
+        return undefined;
+    if (!base)
+        return override;
+    if (!override)
+        return base;
+    const merged = new Map(base);
+    for (const [key, validator] of override) {
+        merged.set(key, validator);
+    }
+    return merged;
+}

package/dist/schema-compat.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Schema compatibility check — verifies that a StackItem's declared
+ * `actionSpec` / `streamSpec` schemas line up with the input/output
+ * schemas of the tools they reference. Wired at two canonical check
+ * points: `ggui_push` validation (defensive, fires when the
+ * generator eventually emits contract) and blueprint registration
+ * (the console blueprint-try endpoint — the real-world site where a
+ * StackItem with pre-declared `actionSpec` / `streamSpec` and tool
+ * refs lands on a session).
+ *
+ * **Algorithmic primitive** lives in `@ggui-ai/protocol`:
+ *
+ *   - `isSchemaSubset(superset, subset)` answers "can every value
+ *     subset accepts also pass superset?".
+ *   - `zodToJsonSchema(...)` converts a tool's ZodRawShape
+ *     `inputSchema` / `outputSchema` to the JsonSchema shape the
+ *     subset algorithm consumes.
+ *
+ * **What this module adds.** A small layer that walks a StackItem's
+ * `actionSpec` + `streamSpec`, resolves each declared `tool` ref
+ * against a toolName → ZodRawShape registry, runs the appropriate
+ * subset check, and reports a stable {@link SchemaCompatReport}. The
+ * caller (console endpoint, push handler — later) decides whether
+ * a non-empty report should throw, warn, or be ignored per the
+ * {@link SchemaCompatMode} policy flag.
+ *
+ * **Direction semantics (load-bearing).**
+ *
+ *   - For `actionSpec[name].schema` + `tool`: the action's payload
+ *     is sent INTO the tool, so the action schema must be a subset
+ *     of the tool's `inputSchema`. Compat relation:
+ *     `isSchemaSubset(toolInputSchema, actionSchema)`.
+ *   - For `streamSpec[channel].schema` + `tool`: the tool's return
+ *     value is emitted OUT on the channel. Every value the tool
+ *     returns MUST be accepted by the channel schema (otherwise a
+ *     tool-fired refresh would emit a payload that subscribers
+ *     reject). The channel schema is therefore the PERMISSIVE side
+ *     and the tool's return is the restricted side. Compat relation:
+ *     `isSchemaSubset(channelSchema, toolReturnSchema)` — i.e.
+ *     "every toolReturn-accepted value is also channelSchema-
+ *     accepted".
+ *
+ *     Note: the `StreamChannelEntry.schema` docstring phrases this
+ *     as "the tool's returns MUST be a superset of channel schema".
+ *     That historical phrasing is author-facing and slightly
+ *     misleading if read literally as set-theoretic superset of
+ *     accepted-values; the semantic intent is the one encoded here
+ *     — EVERY tool return passes channel validation.
+ */
+import type { ZodRawShape } from 'zod';
+import { type SubsetViolation, type ActionSpec, type StreamSpec } from '@ggui-ai/protocol';
+/**
+ * Stance the host takes when a check surfaces violations.
+ *
+ *   - `'reject'` (default) — throw {@link SchemaCompatError} so the
+ *     containing request fails before the stack item commits /
+ *     before the blueprint registers. The canonical enforcement
+ *     posture for launch.
+ *   - `'warn'` — return the report without throwing. The caller is
+ *     expected to log the violations on an observable surface
+ *     (logger, telemetry). Used during migration windows when an
+ *     operator wants to surface mismatches without breaking
+ *     existing flows.
+ *   - `'off'` — skip the check entirely. Test convenience;
+ *     explicit opt-out.
+ */
+export type SchemaCompatMode = 'reject' | 'warn' | 'off';
+/**
+ * Default mode applied when the host does not override. Matches the
+ * Item 5 brief default.
+ */
+export declare const DEFAULT_SCHEMA_COMPAT_MODE: SchemaCompatMode;
+/**
+ * Per-action or per-channel compat finding. Preserves the underlying
+ * subset violations so downstream messaging can surface any level of
+ * detail the operator wants.
+ */
+export interface SchemaCompatFinding {
+    /**
+     * Which spec side produced this finding. `'action'` for an
+     * `actionSpec[name]` tool ref; `'stream'` for a
+     * `streamSpec[channel].tool` ref. Consumers can branch on this
+     * when rendering the cause.
+     */
+    readonly kind: 'action' | 'stream';
+    /** Action name or channel name. */
+    readonly specName: string;
+    /** Tool name the spec referenced. */
+    readonly toolName: string;
+    /** One of:
+     *   - `'tool-not-found'`  — the ref's tool is not registered on
+     *     the composed handler set. (Author bug — matching the
+     *     existing `TOOL_NOT_FOUND` contract semantics, but surfaced
+     *     before any envelope reaches the agentic loop.)
+     *   - `'schema-mismatch'` — the subset check failed with at least
+     *     one violation. See {@link SchemaCompatFinding.violations}.
+     */
+    readonly reason: 'tool-not-found' | 'schema-mismatch';
+    /** Subset violations carried through for rich error rendering.
+     *  Empty array when `reason: 'tool-not-found'`. */
+    readonly violations: readonly SubsetViolation[];
+}
+/**
+ * Aggregate compat report. A `compatible: true` report is the
+ * happy path — the caller commits its side effect. A
+ * `compatible: false` report enumerates every failing spec entry.
+ */
+export interface SchemaCompatReport {
+    readonly compatible: boolean;
+    readonly findings: readonly SchemaCompatFinding[];
+}
+/**
+ * Narrow shape of what the check helper needs from each registered
+ * tool. Satisfied by `SharedHandler<ZodRawShape, ZodRawShape>` — the
+ * two schema fields are the only consumed inputs.
+ */
+export interface ToolSchemaRef {
+    readonly name: string;
+    readonly inputSchema: ZodRawShape;
+    readonly outputSchema: ZodRawShape;
+}
+/**
+ * Narrow shape of the StackItem subset the checker consumes — the
+ * two spec fields PLUS the contract's own tool catalog. Accepts any
+ * object carrying them, so both `@ggui-ai/protocol::StackItem` and
+ * the console endpoint's manifest contract shape work without a cast.
+ *
+ * `agentCapabilities.tools` is the contract author's declared catalog
+ * of every tool the contract references. Tools listed here but NOT
+ * registered on the composing server are CROSS-MCP references — the
+ * agent intends to call them on a different MCP server in its
+ * toolbox. The compat checker accepts these without a server-side
+ * schema check (we can't validate a remote server's tool schema from
+ * here; the agent owns the cross-MCP call).
+ */
+export interface StackItemContractShape {
+    readonly actionSpec?: ActionSpec;
+    readonly streamSpec?: StreamSpec;
+    readonly agentCapabilities?: {
+        readonly tools?: Readonly<Record<string, unknown>>;
+    };
+}
+/**
+ * Thrown when `schemaCompatCheck: 'reject'` surfaces at least one
+ * finding. Carries the full {@link SchemaCompatReport} so callers
+ * can log / surface the detail beyond the `message` string.
+ */
+export declare class SchemaCompatError extends Error {
+    readonly report: SchemaCompatReport;
+    constructor(report: SchemaCompatReport, context: string);
+}
+/**
+ * Check a StackItem's `actionSpec` / `streamSpec` entries against
+ * the tool registry. See {@link SchemaCompatMode} for policy
+ * semantics.
+ *
+ * Returns a {@link SchemaCompatReport}. When `mode === 'reject'`
+ * AND findings exist, throws {@link SchemaCompatError} instead —
+ * the report is still available on `error.report`.
+ *
+ * `context` is a short string naming the call site (e.g.
+ * `"ggui_push"`, `"console blueprint-try:<blueprintId>"`). Shows
+ * up in thrown error messages so an operator reading logs sees
+ * which ingress surfaced the mismatch.
+ */
+export declare function checkStackItemSchemaCompat(stackItem: StackItemContractShape, tools: Iterable<ToolSchemaRef>, mode: SchemaCompatMode, context: string): SchemaCompatReport;
+//# sourceMappingURL=schema-compat.d.ts.map

package/dist/schema-compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,UAAU,EAChB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,gBAA2B,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACnC,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,iBAAiB,CAAC;IACtD;uDACmD;IACnD,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACnD;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC;CACpC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,iBAAiB,CAAC,EAAE;QAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;KACpD,CAAC;CACH;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;gBACxB,MAAM,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM;CAKxD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,sBAAsB,EACjC,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC9B,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,GACd,kBAAkB,CA0HpB"}

package/dist/schema-compat.js

@@ -0,0 +1,187 @@
+import { isSchemaSubset, zodToJsonSchema, } from '@ggui-ai/protocol';
+/**
+ * Default mode applied when the host does not override. Matches the
+ * Item 5 brief default.
+ */
+export const DEFAULT_SCHEMA_COMPAT_MODE = 'reject';
+/**
+ * Thrown when `schemaCompatCheck: 'reject'` surfaces at least one
+ * finding. Carries the full {@link SchemaCompatReport} so callers
+ * can log / surface the detail beyond the `message` string.
+ */
+export class SchemaCompatError extends Error {
+    report;
+    constructor(report, context) {
+        super(formatReport(report, context));
+        this.name = 'SchemaCompatError';
+        this.report = report;
+    }
+}
+/**
+ * Check a StackItem's `actionSpec` / `streamSpec` entries against
+ * the tool registry. See {@link SchemaCompatMode} for policy
+ * semantics.
+ *
+ * Returns a {@link SchemaCompatReport}. When `mode === 'reject'`
+ * AND findings exist, throws {@link SchemaCompatError} instead —
+ * the report is still available on `error.report`.
+ *
+ * `context` is a short string naming the call site (e.g.
+ * `"ggui_push"`, `"console blueprint-try:<blueprintId>"`). Shows
+ * up in thrown error messages so an operator reading logs sees
+ * which ingress surfaced the mismatch.
+ */
+export function checkStackItemSchemaCompat(stackItem, tools, mode, context) {
+    if (mode === 'off') {
+        return { compatible: true, findings: [] };
+    }
+    // Build a one-pass name → tool map. Callers pass the composed
+    // handler list; the map is cheap to rebuild per-check because
+    // the input tool list is typically <50 entries.
+    const byName = new Map();
+    for (const t of tools)
+        byName.set(t.name, t);
+    // Cross-MCP escape hatch: tools the contract author declared in
+    // `agentCapabilities.tools` are accepted even when they don't
+    // exist in the server's registry — the agent intends to call them
+    // on a different MCP server in its toolbox. We can't validate
+    // their inputSchema/outputSchema from here (no access to the
+    // remote tool definition); cross-MCP shape compatibility is the
+    // agent's responsibility. Same-server tools still get the full
+    // server-driven subset check below.
+    const contractDeclaredTools = new Set(Object.keys(stackItem.agentCapabilities?.tools ?? {}));
+    const findings = [];
+    // actionSpec — each action.tool's inputSchema must be a superset
+    // of action.schema. A void action (no schema) paired with a tool
+    // that requires input is flagged specifically: the wire sends
+    // nothing, the tool demands something, so the compat relation is
+    // "empty-object ⊆ tool-input" — which fails whenever the tool has
+    // required fields.
+    const actionSpec = stackItem.actionSpec ?? {};
+    for (const [actionName, entry] of Object.entries(actionSpec)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const toolName = entry.nextStep;
+        if (typeof toolName !== 'string' || toolName.length === 0)
+            continue;
+        const tool = byName.get(toolName);
+        if (!tool) {
+            // Tool not in server registry. Check the cross-MCP escape
+            // hatch — if the contract declared it in agentCapabilities.tools,
+            // skip the server-side check entirely (agent owns cross-MCP
+            // validation).
+            if (contractDeclaredTools.has(toolName))
+                continue;
+            findings.push({
+                kind: 'action',
+                specName: actionName,
+                toolName,
+                reason: 'tool-not-found',
+                violations: [],
+            });
+            continue;
+        }
+        const toolInput = zodToJsonSchema(tool.inputSchema);
+        // Void action (no schema) — model the wire shape as the empty
+        // object schema. The subset check reports required-field
+        // violations only — an unconstrained tool with no required
+        // fields stays compatible.
+        const actionSchema = entry.schema ?? {
+            type: 'object',
+            properties: {},
+            additionalProperties: false,
+        };
+        const result = isSchemaSubset(toolInput, actionSchema);
+        if (!result.compatible) {
+            findings.push({
+                kind: 'action',
+                specName: actionName,
+                toolName,
+                reason: 'schema-mismatch',
+                violations: result.violations,
+            });
+        }
+    }
+    // streamSpec — each channel.tool's outputSchema must be a superset
+    // of channel.schema (inverted direction from actions).
+    const streamSpec = stackItem.streamSpec ?? {};
+    for (const [channelName, entry] of Object.entries(streamSpec)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const toolName = entry.tool;
+        if (typeof toolName !== 'string' || toolName.length === 0)
+            continue;
+        const channelSchema = entry.schema;
+        if (!channelSchema)
+            continue;
+        const tool = byName.get(toolName);
+        if (!tool) {
+            // Cross-MCP escape hatch — symmetric with the actionSpec arm.
+            if (contractDeclaredTools.has(toolName))
+                continue;
+            findings.push({
+                kind: 'stream',
+                specName: channelName,
+                toolName,
+                reason: 'tool-not-found',
+                violations: [],
+            });
+            continue;
+        }
+        const toolOutput = zodToJsonSchema(tool.outputSchema);
+        // Direction: every tool-returned value must be accepted by the
+        // channel schema. Channel is the superset / permissive side,
+        // tool-return is the restricted side.
+        const result = isSchemaSubset(channelSchema, toolOutput);
+        if (!result.compatible) {
+            findings.push({
+                kind: 'stream',
+                specName: channelName,
+                toolName,
+                reason: 'schema-mismatch',
+                violations: result.violations,
+            });
+        }
+    }
+    const report = {
+        compatible: findings.length === 0,
+        findings,
+    };
+    if (mode === 'reject' && !report.compatible) {
+        throw new SchemaCompatError(report, context);
+    }
+    return report;
+}
+/**
+ * Format a report into a human-readable message suitable for a
+ * thrown error or a log line. Output is deterministic — sorted
+ * by `kind` then `specName` — so tests can pattern-match on the
+ * exact string without ordering flakes.
+ */
+function formatReport(report, context) {
+    if (report.compatible) {
+        return `${context}: SCHEMA_MISMATCH_ERROR (no findings — internal error)`;
+    }
+    const sorted = [...report.findings].sort((a, b) => {
+        if (a.kind !== b.kind)
+            return a.kind < b.kind ? -1 : 1;
+        return a.specName < b.specName ? -1 : a.specName > b.specName ? 1 : 0;
+    });
+    const lines = sorted.map((f) => {
+        if (f.reason === 'tool-not-found') {
+            return `- ${f.kind} "${f.specName}" references tool "${f.toolName}" which is not registered`;
+        }
+        const firstViol = f.violations[0];
+        const suffix = firstViol
+            ? ` — ${firstViol.message}` +
+                (f.violations.length > 1
+                    ? ` (${f.violations.length - 1} more violation${f.violations.length > 2 ? 's' : ''})`
+                    : '')
+            : '';
+        return `- ${f.kind} "${f.specName}" (tool "${f.toolName}") — schema mismatch${suffix}`;
+    });
+    return [
+        `${context}: SCHEMA_MISMATCH_ERROR — ${report.findings.length} finding${report.findings.length > 1 ? 's' : ''}`,
+        ...lines,
+    ].join('\n');
+}

package/dist/security-headers-middleware.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Security headers middleware.
+ *
+ * Sets three defense-in-depth headers on every response:
+ *
+ *   - `X-Frame-Options: DENY` — clickjacking guard.
+ *   - `Referrer-Policy: strict-origin-when-cross-origin` — drops the
+ *     full URL on cross-origin navigations; keeps it on same-origin.
+ *   - `X-Content-Type-Options: nosniff` — content-type sniffing off.
+ *
+ * Deliberately does NOT set `Content-Security-Policy` — embedded UI
+ * routes manage CSP separately so per-page nonces stay correct. Don't
+ * double-set: if a header is already on the response when the
+ * middleware runs, leave it alone.
+ *
+ * `skipPathPrefixes` lets the API surface stay headerless. Default
+ * skips:
+ *   - `/mcp` — claude.ai's connector consumes that endpoint cross-
+ *     origin, and X-Frame-Options/Referrer-Policy aren't needed for
+ *     a non-rendered JSON wire.
+ *   - `/r` + `/preview` — the renderer routes are the iframe-target
+ *     surfaces MCP Apps hosts (claude.ai, our chat shell, anyone
+ *     embedding the bootstrap meta) must be able to load. Setting
+ *     `X-Frame-Options: DENY` on these would be a direct protocol
+ *     violation. Operators tightening for prod can override via
+ *     {@link SecurityHeadersMiddlewareOptions.skipPathPrefixes} +
+ *     route-level CSP `frame-ancestors` if they need a stricter
+ *     allowlist than "any origin can embed".
+ */
+import type { RequestHandler } from 'express';
+export interface SecurityHeadersMiddlewareOptions {
+    readonly skipPathPrefixes?: ReadonlyArray<string>;
+}
+/** Returns an Express middleware that sets the standard ggui security
+ *  headers — only when not already present on the response, and only
+ *  on paths NOT matched by `skipPathPrefixes`. */
+export declare function createSecurityHeadersMiddleware(opts?: SecurityHeadersMiddlewareOptions): RequestHandler;
+//# sourceMappingURL=security-headers-middleware.d.ts.map

package/dist/security-headers-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-headers-middleware.d.ts","sourceRoot":"","sources":["../src/security-headers-middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAc9C,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACnD;AAED;;kDAEkD;AAClD,wBAAgB,+BAA+B,CAC7C,IAAI,GAAE,gCAAqC,GAC1C,cAAc,CAgBhB"}

package/dist/security-headers-middleware.js

@@ -0,0 +1,30 @@
+const HEADERS = [
+    ['X-Frame-Options', 'DENY'],
+    ['Referrer-Policy', 'strict-origin-when-cross-origin'],
+    ['X-Content-Type-Options', 'nosniff'],
+];
+const DEFAULT_SKIP_PATH_PREFIXES = [
+    '/mcp',
+    '/r',
+    '/preview',
+];
+/** Returns an Express middleware that sets the standard ggui security
+ *  headers — only when not already present on the response, and only
+ *  on paths NOT matched by `skipPathPrefixes`. */
+export function createSecurityHeadersMiddleware(opts = {}) {
+    const skips = opts.skipPathPrefixes ?? DEFAULT_SKIP_PATH_PREFIXES;
+    return (req, res, next) => {
+        for (const prefix of skips) {
+            if (req.path === prefix || req.path.startsWith(prefix + '/')) {
+                next();
+                return;
+            }
+        }
+        for (const [name, value] of HEADERS) {
+            if (res.getHeader(name) === undefined) {
+                res.setHeader(name, value);
+            }
+        }
+        next();
+    };
+}