mikser-io 7.6.1 → 7.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mikser-io",
-	"version": "7.6.1",
+	"version": "7.8.1",
 	"description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
 	"main": "index.js",
 	"scripts": {

package/src/engine.js

@@ -133,6 +133,34 @@ export async function setup(options) {
                 : Number(runtime.options.server) || 3001
             logger.info('Server starting on port %d', runtime.options.port)
 
+            // Trust-proxy: when mikser is behind a reverse proxy
+            // (nginx, Caddy, an Express app, ngrok with edge), the
+            // socket peer is the proxy — not the real client. Setting
+            // trust proxy makes Express's req.ip walk X-Forwarded-For
+            // back to the original requester, which is what mikser's
+            // loopback-only auth check compares against.
+            //
+            // Accepted values (Express semantics):
+            //   true                 — trust every hop (only safe when
+            //                          the proxy strips/rewrites
+            //                          X-Forwarded-* headers)
+            //   'loopback'           — trust 127.0.0.1, ::1, and other
+            //                          loopback addresses (correct for
+            //                          a proxy on the same host)
+            //   '10.0.0.0/8'         — trust a specific subnet
+            //   false (default)      — no trust; req.ip == socket peer
+            //
+            // Without this and behind a proxy, mikser sees every
+            // request as coming from the proxy's loopback address and
+            // unauthenticated requests through the proxy would pass
+            // the loopback gate. The startup warning below catches
+            // some of those misconfigurations.
+            const trustProxy = runtime.config.server?.trustProxy
+            if (trustProxy !== undefined) {
+                runtime.options.app.set('trust proxy', trustProxy)
+                logger.info('Server trust proxy: %s', String(trustProxy))
+            }
+
             // CORS — a server exists to be fetched, and in dev the
             // frontend is almost always on a different origin (a dev
             // server on another port, a separate domain). So CORS is ON
@@ -212,8 +240,8 @@ export async function setup(options) {
             // server is fully reachable over HTTP for AI clients.
             if (runtime.options.mcp && runtime.options.mcpPath) {
                 const { mountMcpOnExpress } = await import('./mcp.js')
+                // mcp.js logs per-endpoint as it mounts — no extra log here.
                 await mountMcpOnExpress(runtime.options.app, runtime.options.mcp, runtime.options.mcpPath)
-                logger.info('MCP mounted: %s', runtime.options.mcpPath)
             }
 
             // Serve the output folder as the catch-all static route.
@@ -222,11 +250,13 @@ export async function setup(options) {
             // plugin's router falls through to the static handler and
             // gets served from <outputFolder>.
             runtime.options.app.use(express.static(runtime.options.outputFolder))
-            logger.info('Serving %s as /', runtime.options.outputFolder.replace(runtime.options.workingFolder + '/', ''))
+            logger.info('Serving %s at http://localhost:%d/',
+                runtime.options.outputFolder.replace(runtime.options.workingFolder + '/', ''),
+                runtime.options.port)
 
             await new Promise(resolve => {
                 runtime.options.app.listen(runtime.options.port, () => {
-                    logger.info('Server listening on port %d', runtime.options.port)
+                    logger.info('Server listening: http://localhost:%d', runtime.options.port)
                     resolve()
                 })
             })

package/src/mcp.js

@@ -20,8 +20,26 @@
 import { randomUUID } from 'node:crypto'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import { minimatch } from 'minimatch'
 import packageInfo from '../package.json' with { type: 'json' }
 import runtime from './runtime.js'
+import { isLoopback } from './utils.js'
+
+// Pattern matcher for endpoint tools/resources filters. Accepts
+// '*', an array of patterns, or undefined (= allow all). Glob
+// patterns like 'mikser_api_*' or 'mikser_*_render' work through
+// minimatch — same library mikser uses for content matching, so
+// the syntax is consistent across the codebase.
+function matchesAny(name, patterns) {
+    if (patterns == null) return true
+    if (patterns === '*') return true
+    if (!Array.isArray(patterns)) return false
+    for (const p of patterns) {
+        if (p === '*') return true
+        if (minimatch(name, p)) return true
+    }
+    return false
+}
 
 let pinoLevelToMcp = (pinoLevel) => {
     if (pinoLevel >= 50) return 'error'
@@ -55,10 +73,25 @@ export function createMcpSubstrate() {
     const LOG_BUFFER_CAP = 500
     const logBuffer = []
 
-    function bind(server) {
-        for (const args of registrations.tools) server.registerTool(...args)
-        for (const args of registrations.resources) server.registerResource(...args)
-        for (const args of registrations.prompts) server.registerPrompt(...args)
+    function bind(server, filters = {}) {
+        const { allowedTools, allowedResources, allowedPrompts } = filters
+        for (const args of registrations.tools) {
+            if (!matchesAny(args[0], allowedTools)) continue
+            server.registerTool(...args)
+        }
+        for (const args of registrations.resources) {
+            // Resource registrations are (name, uri, config, handler).
+            // Filter on the URI since that's the addressable identifier
+            // (`mikser://lifecycle` reads more naturally as the filter
+            // target than the short `mikser-lifecycle` name).
+            const uri = typeof args[1] === 'string' ? args[1] : args[0]
+            if (!matchesAny(uri, allowedResources)) continue
+            server.registerResource(...args)
+        }
+        for (const args of registrations.prompts) {
+            if (!matchesAny(args[0], allowedPrompts)) continue
+            server.registerPrompt(...args)
+        }
     }
 
     const substrate = {
@@ -95,13 +128,20 @@ export function createMcpSubstrate() {
         },
 
         // Create a fresh McpServer pre-loaded with every recorded
-        // registration. Called by the transport mount per new session.
-        _createServer() {
+        // registration that passes the endpoint's filters. Called by
+        // the transport mount per new session.
+        //
+        // Filters take patterns (exact name or glob via minimatch):
+        //   allowedTools:     ['mikser_api_*', 'mikser_ping']
+        //   allowedResources: ['mikser://lifecycle', 'mikser://logs/*']
+        // Omit a filter (or pass '*') to allow everything in that
+        // category — that's the backward-compat default.
+        _createServer({ allowedTools, allowedResources, allowedPrompts } = {}) {
             const server = new McpServer(
                 { name: 'mikser-io', version: packageInfo.version },
                 { capabilities: { tools: {}, resources: {}, logging: {} } },
             )
-            bind(server)
+            bind(server, { allowedTools, allowedResources, allowedPrompts })
             return server
         },
         _attach(server) { activeServers.add(server) },
@@ -308,33 +348,99 @@ function serverInfo() {
         serves: opts.outputFolder ?? null,
         mcpPath: opts.mcpPath ?? null,
         mcpUrl: base && opts.mcpPath ? `${base}${opts.mcpPath}` : null,
-        // Preview URLs are returned directly by mikser_preview (api
-        // plugin), so we don't advertise a path convention here —
-        // doing so would be a lie when the api plugin isn't loaded.
+        // Preview URLs are returned directly by mikser_preview_render
+        // (preview plugin), so we don't advertise a path convention here —
+        // doing so would be a lie when the preview plugin isn't loaded.
     }
 }
 
 /**
- * Mount the MCP substrate on an Express app at the given path
- * (default `/mcp`). Each connecting client gets its own
- * McpServer + StreamableHTTPServerTransport pair (SDK constraint).
- * Sessions are tracked by `mcp-session-id` header — initialize
- * requests open a new session; subsequent requests echo their id.
+ * Mount the MCP substrate on an Express app. Two modes:
+ *
+ *   1. Single endpoint (backward compat): no `runtime.config.mcp.endpoints`
+ *      → mounts one open endpoint at `defaultPath` (default `/mcp`) with
+ *      all tools, all resources, no token. Matches the v7.0-7.6 shape.
+ *
+ *   2. Multiple endpoints: with `runtime.config.mcp.endpoints` set →
+ *      each endpoint mounts at `<mcp.base>/<name>` (default base `/mcp`)
+ *      with its own filters (`tools`, `resources`) and optional
+ *      `token` for Bearer auth.
+ *
+ * Each endpoint is its own session map — sessions don't cross endpoints.
+ * Same noun and shape as the api plugin's `endpoints` config.
  */
-export async function mountMcpOnExpress(app, substrate, path = '/mcp') {
-    // sessionId → transport. POSTs with an existing id route back
-    // to that transport so the SDK's session state stays consistent.
+export async function mountMcpOnExpress(app, substrate, defaultPath = '/mcp') {
+    const endpoints = runtime.config.mcp?.endpoints
+    const base = runtime.config.mcp?.base ?? defaultPath
+
+    if (endpoints && Object.keys(endpoints).length > 0) {
+        for (const [name, ep] of Object.entries(endpoints)) {
+            mountEndpoint(app, substrate, `${base}/${name}`, ep, name)
+        }
+    } else {
+        // Backward-compat single endpoint. With no `mcp.endpoints`
+        // configured, mount one open + loopback-only endpoint — same
+        // safe default as a per-endpoint config with no token. The
+        // boot log line itself (from mountEndpoint) shows the state;
+        // no extra warning needed because the default IS the safe one.
+        mountEndpoint(app, substrate, defaultPath, {}, null)
+    }
+}
+
+function mountEndpoint(app, substrate, path, ep, endpointName) {
     const transports = new Map()
+    const expectedAuth = ep.token ? `Bearer ${ep.token}` : null
 
     async function handle(req, res, body) {
+        // Auth rule (uniform across mikser plugins):
+        //   - Token presented and matches → allow (from anywhere)
+        //   - Token presented and doesn't match → 401
+        //   - No token presented → require loopback unless allowRemote
+        //
+        // This means an endpoint with a token can still be called from
+        // localhost without the token — the "trusted host" model. Same
+        // pattern Postgres trust-auth and Redis default use. If the host
+        // is compromised mikser's tools are the least of your worries.
+        const presented = req.headers.authorization
+        if (expectedAuth) {
+            if (presented && presented !== expectedAuth) {
+                res.status(401).json({
+                    jsonrpc: '2.0',
+                    error: { code: -32001, message: 'Invalid MCP token' },
+                    id: null,
+                })
+                return
+            }
+            // No header presented falls through to the loopback check
+            // below — token-gated endpoints still accept loopback.
+        }
+        if (!presented || presented !== expectedAuth) {
+            if (!ep.allowRemote && !isLoopback(req.ip)) {
+                res.status(403).json({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32001,
+                        message: expectedAuth
+                            ? 'Token required from non-loopback sources'
+                            : 'Endpoint accepts loopback connections only — configure a token or set allowRemote: true to enable remote access',
+                    },
+                    id: null,
+                })
+                return
+            }
+        }
+
         const sessionId = req.headers['mcp-session-id']
         if (sessionId && transports.has(sessionId)) {
             return transports.get(sessionId).handleRequest(req, res, body)
         }
 
-        // No matching session — assume a new initialize request
-        // (the SDK will reject if it isn't actually an initialize).
-        const server = substrate._createServer()
+        // New session — server filtered for this endpoint's surface.
+        const server = substrate._createServer({
+            allowedTools:     ep.tools,
+            allowedResources: ep.resources,
+            allowedPrompts:   ep.prompts,
+        })
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: () => randomUUID(),
             onsessioninitialized: (id) => {
@@ -353,6 +459,32 @@ export async function mountMcpOnExpress(app, substrate, path = '/mcp') {
     app.post(path, (req, res) => handle(req, res, req.body))
     app.get(path,  (req, res) => handle(req, res))
     app.delete(path, (req, res) => handle(req, res))
+
+    const logger = runtime.engine?.logger
+    if (logger) {
+        const toolsLabel = ep.tools == null || ep.tools === '*'
+            ? '*'
+            : Array.isArray(ep.tools) ? ep.tools.join(',') : String(ep.tools)
+        // Three reachability states: token (anyone with the token from
+        // anywhere), loopback-only (no token + no allowRemote, default),
+        // or REMOTE OPEN (no token + allowRemote, deliberate exposure).
+        // The all-caps "REMOTE OPEN" mirrors the boot warning style so
+        // an operator scanning startup output sees the risk.
+        const authLabel = ep.token
+            ? 'token'
+            : (ep.allowRemote ? 'public, REMOTE OPEN' : 'public, loopback-only')
+        // Print as a full URL when we know the port so the operator can
+        // copy/click straight from the log. Falls back to bare path for
+        // external-app setups where the engine doesn't own the listener.
+        const location = runtime.options.port
+            ? `http://localhost:${runtime.options.port}${path}`
+            : path
+        if (endpointName) {
+            logger.info('MCP endpoint mounted: %s (tools=[%s] [%s])', location, toolsLabel, authLabel)
+        } else {
+            logger.info('MCP mounted: %s [%s]', location, authLabel)
+        }
+    }
 }
 
 /**

package/src/plugins/api.js

@@ -5,7 +5,7 @@ import _ from 'lodash'
 import sift from 'sift'
 import { z } from 'zod'
 import { useRenderer, useCollection } from '../api.js'
-import { mimeForEntity } from '../utils.js'
+import { mimeForEntity, isLoopback } from '../utils.js'
 
 // Mongo-style operators recognised in URL query params as `<path>.$<op>=...`.
 // $in / $nin take comma-separated values; $exists takes a truthy/falsy
@@ -309,7 +309,7 @@ export default ({
         // Preview workflow (render → cache → URL) lives in its own
         // plugin (src/plugins/preview.js) as of v7.3.0. The api plugin
         // stays focused on REST catalog access; preview is a separate
-        // domain. To use mikser_preview, load `preview` alongside `api`.
+        // domain. To use mikser_preview_render, load `preview` alongside `api`.
 
         // cachedEndpoints is hoisted above (shared with onFinalize).
         // Per-endpoint setup loop pushes into it when cache: true is set.
@@ -403,10 +403,33 @@ export default ({
             }
             const cacheEnabled = ep.cache === true
 
+            // Uniform mikser auth rule (same as MCP endpoints):
+            //   - Token presented and matches → allow (from anywhere)
+            //   - Token presented and doesn't match → 401
+            //   - No token presented → require loopback unless allowRemote
+            //
+            // Endpoints with a token are still reachable from loopback
+            // without the token — the "trusted local host" model. To
+            // require the token everywhere, run mikser bound to a
+            // non-loopback interface only (or behind a proxy that
+            // doesn't forward loopback origin).
+            const expectedAuth = ep.token ? `Bearer ${ep.token}` : null
             const auth = (req, res, next) => {
-                if (!ep.token) return next()
-                if (req.headers.authorization === `Bearer ${ep.token}`) return next()
-                res.status(401).json({ error: 'Unauthorized' })
+                const presented = req.headers.authorization
+                if (expectedAuth && presented && presented !== expectedAuth) {
+                    return res.status(401).json({ error: 'Unauthorized' })
+                }
+                if (presented === expectedAuth && expectedAuth) {
+                    return next()   // valid token from anywhere
+                }
+                if (ep.allowRemote || isLoopback(req.ip)) {
+                    return next()
+                }
+                res.status(403).json({
+                    error: expectedAuth
+                        ? 'Token required from non-loopback sources'
+                        : 'Endpoint accepts loopback connections only — configure a token or set allowRemote: true to enable remote access',
+                })
             }
 
             const allow = (op) => (req, res, next) => {
@@ -610,9 +633,17 @@ export default ({
             })
 
             app.use(`${base}/${name}`, router)
-            logger.info('Api endpoint mounted: %s/%s (ops=[%s] %s)',
-                base, name, [...allowedOps].join(','),
-                ep.token ? '[token]' : '[public]')
+            // Mirror MCP's boot log shape — same three reachability states.
+            const authLabel = ep.token
+                ? 'token'
+                : (ep.allowRemote ? 'public, REMOTE OPEN' : 'public, loopback-only')
+            // Full URL when the engine owns the listener (port is known).
+            // Falls back to the path alone for external-app setups.
+            const location = runtime.options.port
+                ? `http://localhost:${runtime.options.port}${base}/${name}`
+                : `${base}/${name}`
+            logger.info('Api endpoint mounted: %s (ops=[%s] [%s])',
+                location, [...allowedOps].join(','), authLabel)
         }
 
         // MCP tool registrations. MCP is in-process: whoever can reach
@@ -637,7 +668,7 @@ export default ({
             })
 
             mcp.simpleTool(
-                'mikser_list_entities',
+                'mikser_api_list_entities',
                 'List entities from mikser\'s catalog with optional filter / sort / projection. Use this for "show me all documents about X" or "what entities are in collection Y." Returns paginated results in the same envelope shape as the HTTP /entities endpoint.',
                 {
                     filter: z.record(z.any()).optional().describe('Mongo-style filter (sift-compatible). Defaults to no filter — every entity.'),
@@ -665,14 +696,14 @@ export default ({
                             hasNext: effectiveSkip + effectiveLimit < total,
                         })
                     } catch (err) {
-                        logger.error('MCP mikser_list_entities error: %s', err.message)
+                        logger.error('MCP mikser_api_list_entities error: %s', err.message)
                         return fail(err.message)
                     }
                 },
             )
 
             mcp.simpleTool(
-                'mikser_read_entity',
+                'mikser_api_read_entity',
                 'Read a single entity by its catalog id (e.g. "/documents/about.md"). Returns the full entity record or null when not found. Pass include: ["content"] to also fetch the source file content from disk — useful for reading a layout template, document frontmatter+body, or any text-format source without dropping out to the filesystem.',
                 {
                     id: z.string().describe('Catalog id of the entity to read.'),
@@ -694,7 +725,7 @@ export default ({
                             // Heuristic — read content only for text-like
                             // formats. Binary types (png, pdf, mp4, etc.)
                             // get a marker so the caller knows to use a
-                            // different tool (mikser_render, or fetch
+                            // different tool (mikser_api_render, or fetch
                             // directly) rather than expecting bytes back.
                             const TEXT_EXTS = new Set([
                                 'md', 'markdown', 'html', 'htm', 'xhtml',
@@ -713,20 +744,20 @@ export default ({
                                     entity.contentError = err.message
                                 }
                             } else {
-                                entity.contentSkipped = `Non-text format (.${ext}). Use mikser_render to materialize output or read the file directly at entity.uri.`
+                                entity.contentSkipped = `Non-text format (.${ext}). Use mikser_api_render to materialize output or read the file directly at entity.uri.`
                             }
                         }
 
                         return ok(entity)
                     } catch (err) {
-                        logger.error('MCP mikser_read_entity error: %s', err.message)
+                        logger.error('MCP mikser_api_read_entity error: %s', err.message)
                         return fail(err.message)
                     }
                 },
             )
 
             mcp.simpleTool(
-                'mikser_update_entity',
+                'mikser_api_update_entity',
                 'Create or update a content file inside a mikser collection. The file is written to disk and the next lifecycle cycle picks it up — same path the HTTP PUT /entities endpoint takes. Use this to author new documents, layouts, or other content from AI.',
                 {
                     collection:   z.string().describe('Collection name (e.g. "documents", "layouts").'),
@@ -738,14 +769,14 @@ export default ({
                         await useCollection(runtime, collection).write(relativePath, content)
                         return ok({ ok: true, collection, relativePath })
                     } catch (err) {
-                        logger.error('MCP mikser_update_entity error: %s', err.message)
+                        logger.error('MCP mikser_api_update_entity error: %s', err.message)
                         return fail(err.message)
                     }
                 },
             )
 
             mcp.simpleTool(
-                'mikser_delete_entity',
+                'mikser_api_delete_entity',
                 'Remove a content file from a mikser collection. Mirrors HTTP DELETE /entities — deletes the source file, and the next lifecycle cycle prunes its rendered outputs from the manifest.',
                 {
                     collection:   z.string().describe('Collection name.'),
@@ -756,15 +787,15 @@ export default ({
                         await useCollection(runtime, collection).remove(relativePath)
                         return ok({ ok: true, collection, relativePath })
                     } catch (err) {
-                        logger.error('MCP mikser_delete_entity error: %s', err.message)
+                        logger.error('MCP mikser_api_delete_entity error: %s', err.message)
                         return fail(err.message)
                     }
                 },
             )
 
             mcp.simpleTool(
-                'mikser_render',
-                'Render a transient entity through the engine pipeline (parse → layouts → resources → render → postprocess) and return the FINAL produced bytes. Use this for "preview this layout against this data" without writing the entity to disk. The returned bytes are the pipeline\'s final output — PDF for a `*.html-pdf.*` layout, MJML-derived HTML for `*.html-mjml.*`, etc. Set options.save=false to skip the disk write; options.catalog=false to prune the catalog row after rendering.',
+                'mikser_api_render',
+                'Render a transient entity through the engine pipeline (parse → layouts → resources → render → postprocess) and return the FINAL produced bytes. Use this for "preview this layout against this data" without writing the entity to disk. The returned bytes are the pipeline\'s final output — PDF for a `*.html-pdf.*` layout, MJML-derived HTML for `*.html-mjml.*`, etc. Set options.save=false to skip the disk write; options.catalog=false to prune the catalog row after rendering. For a clickable preview URL instead of raw bytes, use mikser_preview_render (preview plugin).',
                 {
                     entity:  z.record(z.any()).describe('Entity shape with at least { id, collection } and any meta/content the renderer needs.'),
                     options: z.record(z.any()).optional().describe('Renderer options: { save: false, catalog: false, renderer: "...", postprocessor: "..." }.'),
@@ -801,13 +832,13 @@ export default ({
                             }],
                         }
                     } catch (err) {
-                        logger.error('MCP mikser_render error: %s', err.message)
+                        logger.error('MCP mikser_api_render error: %s', err.message)
                         return fail(err.message)
                     }
                 },
             )
 
-            logger.info('MCP tools registered: list/read/update/delete/render (api plugin)')
+            logger.info('MCP tools registered: mikser_api_{list_entities,read_entity,update_entity,delete_entity,render} (api plugin)')
         }
     })
 

package/src/plugins/layouts.js

@@ -506,7 +506,7 @@ export default ({
         }
     })
 
-    // mikser_inspect_layout lives in the layouts plugin (not core)
+    // mikser_layouts_inspect lives in the layouts plugin (not core)
     // because "what does a layout expect?" is layout-specific knowledge.
     // Follows ADR-0006: domain logic → plugin; the MCP substrate stays
     // in core.
@@ -518,10 +518,10 @@ export default ({
         if (!runtime.options.mcp) return
         const mcp = runtime.options.mcp
         mcp.simpleTool(
-            'mikser_inspect_layout',
+            'mikser_layouts_inspect',
             'Inspect a layout: template source, variables it references, the postprocessor it produces, and sample entities currently using it. Use this to answer "what data does this layout need?" before drafting a preview render — saves a guess-and-render-empty cycle.',
             {
-                id: z.string().describe('Layout id, e.g. "/layouts/reports/royalty.html-pdf.liquid". Use mikser_list_entities with { collection: "layouts" } to discover ids.'),
+                id: z.string().describe('Layout id, e.g. "/layouts/reports/royalty.html-pdf.liquid". Use mikser_api_list_entities with { collection: "layouts" } to discover ids.'),
                 samples: z.number().int().min(0).max(10).optional().describe('How many existing entities currently using this layout to include as data-shape examples. Default 3. Only entities with explicit meta.layout match; auto-matched layouts are not surfaced.'),
             },
             async ({ id, samples = 3 }) => {
@@ -576,13 +576,13 @@ export default ({
                                 samples: sampleEntities,
                                 notes: [
                                     'references.variables is a naive regex pass across liquid/handlebars/eta — false positives possible, but covers the common `{{ document.meta.X }}` and `<%= entity.X %>` patterns.',
-                                    'samples only includes entities with explicit meta.layout. Auto-matched layouts are not listed; use mikser_list_entities with a filename-pattern filter for those.',
+                                    'samples only includes entities with explicit meta.layout. Auto-matched layouts are not listed; use mikser_api_list_entities with a filename-pattern filter for those.',
                                 ],
                             }, null, 2),
                         }],
                     }
                 } catch (err) {
-                    logger.error('MCP mikser_inspect_layout error: %s', err.message)
+                    logger.error('MCP mikser_layouts_inspect error: %s', err.message)
                     return {
                         isError: true,
                         content: [{ type: 'text', text: err.message }],
@@ -591,7 +591,7 @@ export default ({
             },
         )
         const logger = useLogger()
-        logger.info('MCP tool registered: mikser_inspect_layout (layouts plugin)')
+        logger.info('MCP tool registered: mikser_layouts_inspect (layouts plugin)')
     })
 
     return {

package/src/plugins/preview.js

@@ -4,7 +4,7 @@
 //   1. An in-memory cache (Map<filename, { bytes, mime, expiresAt, size }>)
 //      with LRU eviction past a configurable byte cap.
 //   2. An Express GET /preview/:filename route that serves cache entries.
-//   3. The mikser_preview MCP tool, registered on the substrate when
+//   3. The mikser_preview_render MCP tool, registered on the substrate when
 //      --mcp is active.
 //
 // Lives outside the api plugin because preview is not a REST catalog
@@ -20,7 +20,7 @@
 // Library-mode surface: this plugin exposes
 //   runtime.options.preview = { store, get, stats }
 // so any plugin or programmatic caller can stash bytes and get a URL
-// back without going through MCP. The mikser_preview tool is a thin
+// back without going through MCP. The mikser_preview_render tool is a thin
 // wrapper over this surface.
 
 import path from 'node:path'
@@ -124,7 +124,12 @@ export default ({
             }
             res.type(entry.mime).send(entry.bytes)
         })
-        logger.info('Preview route mounted: %s (cache cap: %d MB)', cfg.path, Math.round(cfg.maxBytes / 1024 / 1024))
+        // Full URL when port is known; bare path otherwise. The /:filename
+        // segment is left off — it's filled at request time per preview.
+        const location = runtime.options.port
+            ? `http://localhost:${runtime.options.port}${cfg.path}`
+            : cfg.path
+        logger.info('Preview route mounted: %s (cache cap: %d MB)', location, Math.round(cfg.maxBytes / 1024 / 1024))
     })
 
     // Gating on runtime.options.mcp inside onLoaded matches the route-
@@ -138,11 +143,11 @@ export default ({
         })
 
         mcp.simpleTool(
-            'mikser_preview',
-            'Render an entity through the engine pipeline AND surface the FINAL output as a clickable URL served by the running --server. Use this instead of mikser_render when the user needs to see the result in a browser. The URL serves the pipeline\'s final output — PDF for a `*.html-pdf.*` layout, MJML-derived HTML for `*.html-mjml.*`, etc. Requires --server. Previews live in memory (not on disk, never under outputFolder) and auto-expire — default 10 minutes, clamped 30..3600 seconds.',
+            'mikser_preview_render',
+            'Render an entity through the engine pipeline AND surface the FINAL output as a clickable URL served by the running --server. Use this instead of mikser_api_render when the user needs to see the result in a browser. The URL serves the pipeline\'s final output — PDF for a `*.html-pdf.*` layout, MJML-derived HTML for `*.html-mjml.*`, etc. Requires --server. Previews live in memory (not on disk, never under outputFolder) and auto-expire — default 10 minutes, clamped 30..3600 seconds.',
             {
-                entity:  z.record(z.any()).describe('Entity shape with at least { id, collection } and any meta/content the renderer needs. Same shape as mikser_render.'),
-                options: z.record(z.any()).optional().describe('Renderer options. Same as mikser_render, plus { expiresInSeconds: number = 600 } controlling preview TTL.'),
+                entity:  z.record(z.any()).describe('Entity shape with at least { id, collection } and any meta/content the renderer needs. Same shape as mikser_api_render.'),
+                options: z.record(z.any()).optional().describe('Renderer options. Same as mikser_api_render, plus { expiresInSeconds: number = 600 } controlling preview TTL.'),
             },
             async ({ entity = {}, options = {} }) => {
                 const logger = useLogger()
@@ -156,7 +161,7 @@ export default ({
 
                 try {
                     if (!runtime.options.port) {
-                        return fail('mikser_preview requires --server to be running so the preview URL is reachable. Use mikser_render to get raw bytes inline instead.')
+                        return fail('mikser_preview_render requires --server to be running so the preview URL is reachable. Use mikser_api_render to get raw bytes inline instead.')
                     }
 
                     const { expiresInSeconds = config().defaultTtl, ...renderOptions } = options ?? {}
@@ -182,24 +187,24 @@ export default ({
                     const url = `http://localhost:${runtime.options.port}${cfg.path}/${filename}`
                     const bytes = Buffer.isBuffer(result) ? result.length : Buffer.byteLength(result)
 
-                    logger.info('MCP mikser_preview cached %s (%d bytes, ttl %ds): %s', filename, bytes, ttlSec, url)
+                    logger.info('MCP mikser_preview_render cached %s (%d bytes, ttl %ds): %s', filename, bytes, ttlSec, url)
 
                     return ok({
                         previewUrl: url,
                         mimeType: mime,
                         bytes,
                         expiresInSeconds: ttlSec,
-                        instructions: 'Open previewUrl in a browser to view. The preview lives in mikser memory and auto-expires after expiresInSeconds — re-run mikser_preview to refresh.',
+                        instructions: 'Open previewUrl in a browser to view. The preview lives in mikser memory and auto-expires after expiresInSeconds — re-run mikser_preview_render to refresh.',
                     })
                 } catch (err) {
-                    logger.error('MCP mikser_preview error: %s', err.message)
+                    logger.error('MCP mikser_preview_render error: %s', err.message)
                     return fail(err.message)
                 }
             },
         )
 
         const logger = useLogger()
-        logger.info('MCP tool registered: mikser_preview (preview plugin)')
+        logger.info('MCP tool registered: mikser_preview_render (preview plugin)')
     })
 
     return { name: 'preview' }

package/src/utils.js

@@ -40,6 +40,38 @@ export function mimeForEntity(entity) {
     return MIME_BY_EXT[ext] ?? null
 }
 
+// True when `ip` is a loopback address. Handles all three forms:
+//   - IPv4: anything in 127.0.0.0/8
+//   - IPv6: ::1
+//   - IPv4-mapped-in-IPv6: ::ffff:127.x.y.z (what dual-stack stacks return)
+//
+// Used by mikser's auth middleware to honor the "loopback connections are
+// trusted; non-loopback connections must authenticate" rule across plugins.
+// Pass `req.ip` rather than `req.socket.remoteAddress` — Express's req.ip
+// walks `X-Forwarded-For` when trust proxy is configured, which is what
+// reveals the real client through a properly-configured reverse proxy.
+export function isLoopback(ip) {
+    if (!ip || typeof ip !== 'string') return false
+    const addr = ip.startsWith('::ffff:') ? ip.slice(7) : ip
+    if (addr === '::1') return true
+    if (addr === '127.0.0.1') return true
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(addr)
+}
+
+// Express middleware factory: 403s any request whose `req.ip` isn't
+// loopback. Plugins use this to protect routes that should be reachable
+// only from the local machine. Customize the response with `message`.
+//
+// For more nuanced policies (token gate + loopback fallback), plugins
+// usually inline the check using isLoopback() directly — this factory is
+// for the simple "this route is local-only, period" case.
+export function loopbackOnly({ message = 'Endpoint accepts loopback connections only.' } = {}) {
+    return (req, res, next) => {
+        if (isLoopback(req.ip)) return next()
+        res.status(403).json({ error: message })
+    }
+}
+
 export class AbortError extends Error {
     constructor(message) {
         super();

package/ngrok.ymlt

@@ -1,3 +0,0 @@
-version: 3
-agent:
-  authtoken: 3EcICPaDtSN54h63Y5v8g2zKOJ9_5oMnCdXyPmMmKVXH9ba1c