@frontmcp/plugin-skilled-openapi 0.0.1

package/esm/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@frontmcp/plugin-skilled-openapi",
+  "version": "1.0.4",
+  "description": "FrontMCP plugin: serve a customer's OpenAPI spec as skill bundles (signed, OpenAPI-Overlay-based) with hidden per-operation tools mediated by three meta-tools (search_skill / load_skill / execute_action).",
+  "author": "AgentFront <info@agentfront.dev>",
+  "license": "Apache-2.0",
+  "keywords": [
+    "mcp",
+    "frontmcp",
+    "openapi",
+    "skills",
+    "agent-skills",
+    "plugin",
+    "agentfront"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentfront/frontmcp.git",
+    "directory": "plugins/plugin-skilled-openapi"
+  },
+  "bugs": {
+    "url": "https://github.com/agentfront/frontmcp/issues"
+  },
+  "homepage": "https://github.com/agentfront/frontmcp/blob/main/plugins/plugin-skilled-openapi/README.md",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "../index.js",
+  "module": "./index.mjs",
+  "types": "../index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "../package.json",
+    ".": {
+      "require": {
+        "types": "../index.d.ts",
+        "default": "../index.js"
+      },
+      "import": {
+        "types": "../index.d.ts",
+        "default": "./index.mjs"
+      }
+    }
+  },
+  "dependencies": {
+    "@frontmcp/adapters": "1.0.4",
+    "@frontmcp/auth": "1.0.4",
+    "@frontmcp/protocol": "1.0.4",
+    "@frontmcp/sdk": "1.0.4",
+    "@frontmcp/utils": "1.0.4"
+  },
+  "peerDependencies": {
+    "@frontmcp/lazy-zod": "1.0.4"
+  },
+  "devDependencies": {
+    "reflect-metadata": "^0.2.2"
+  }
+}

package/executor/credential-resolver.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Resolves a `vaultRef` string from an `AuthBinding` to a credential value.
+ *
+ * In production, this would be backed by `libs/auth`'s vault. v1.2.0 OSS
+ * ships an in-memory implementation suitable for static-source / npm-source
+ * deployments and demo scenarios; SaaS-managed deployments wire their own
+ * resolver against the customer's secret manager via plugin DI overrides.
+ *
+ * Resolved credentials are scoped: the caller MUST supply a `bundleId` so
+ * the resolver can enforce per-bundle credential allowlists (planned v1.2.x
+ * feature; the interface is shaped for it now).
+ */
+export interface CredentialResolver {
+    /**
+     * Resolve a vault reference. Returns the credential value (e.g. an API key
+     * or bearer token). Returns undefined if the ref is unknown — callers MUST
+     * fail closed (do NOT call without credentials).
+     */
+    resolve(ref: string, opts: {
+        bundleId: string;
+    }): Promise<string | undefined>;
+}
+/**
+ * In-memory resolver — values supplied at construction time. Suitable for
+ * dev / demo / single-tenant. Trailing-newline normalization is applied once
+ * at ingestion (constructor / setForBundle) so resolve() returns the stored
+ * value verbatim and never mutates an intentional secret.
+ *
+ * Bundle scoping: the constructor seeds tenant-wide credentials (the natural
+ * shape of the plugin's `credentials` option for single-tenant demos). When a
+ * bundle needs an override (e.g. a multi-tenant deployment where every bundle
+ * carries its own secret for the same `vaultRef`), call `setForBundle()`. On
+ * resolve, the per-bundle entry wins over the tenant-wide default; if neither
+ * exists the call returns undefined and the executor fails closed.
+ */
+export declare class MemoryCredentialResolver implements CredentialResolver {
+    private readonly defaults;
+    private readonly perBundle;
+    constructor(defaults?: Record<string, string>);
+    /**
+     * Override (or add) a credential for a specific bundle. Per-bundle entries
+     * take precedence over the tenant-wide defaults supplied to the constructor.
+     */
+    setForBundle(bundleId: string, ref: string, value: string): void;
+    resolve(ref: string, opts: {
+        bundleId: string;
+    }): Promise<string | undefined>;
+}
+//# sourceMappingURL=credential-resolver.d.ts.map

package/executor/credential-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-resolver.d.ts","sourceRoot":"","sources":["../../src/executor/credential-resolver.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC/E;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,wBAAyB,YAAW,kBAAkB;IACjE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0C;gBAExD,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM;IAIjD;;;OAGG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAS1D,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAMpF"}

package/executor/openapi-runtime.d.ts

@@ -0,0 +1,33 @@
+import type { FrontMcpLogger } from '@frontmcp/sdk';
+import type { HiddenOpEntry } from '../registry/hidden-op.registry';
+import type { OutboundOptions } from '../skilled-openapi.types';
+import type { CredentialResolver } from './credential-resolver';
+/** Caller-supplied input. Flat keys match `mapper[].inputKey`. */
+export type OperationInput = Record<string, unknown>;
+export interface ExecutionResult {
+    ok: boolean;
+    status: number;
+    data: unknown;
+    contentType?: string;
+    error?: string;
+    responseBytes: number;
+}
+export interface OpenApiRuntimeDeps {
+    outbound: OutboundOptions;
+    resolver: CredentialResolver;
+    allowedHosts: ReadonlySet<string>;
+    logger: FrontMcpLogger;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Execute one hidden operation against the customer's REST API. Returns a
+ * structured envelope; never raw-stringifies the response into model context.
+ */
+export declare function executeOperation(args: {
+    entry: HiddenOpEntry;
+    bundleId: string;
+    input: OperationInput;
+    callerToken?: string;
+    deps: OpenApiRuntimeDeps;
+}): Promise<ExecutionResult>;
+//# sourceMappingURL=openapi-runtime.d.ts.map

package/executor/openapi-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-runtime.d.ts","sourceRoot":"","sources":["../../src/executor/openapi-runtime.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAGhE,kEAAkE;AAClE,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB;AA0HD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,kBAAkB,CAAC;CAC1B,GAAG,OAAO,CAAC,eAAe,CAAC,CA8F3B"}

package/executor/schema-cache.d.ts

@@ -0,0 +1,30 @@
+import { z } from '@frontmcp/lazy-zod';
+export type CompiledSchema = z.ZodTypeAny;
+export interface CompiledOpSchemas {
+    input: CompiledSchema;
+    output: CompiledSchema;
+    /** True when the JSON Schema couldn't be converted (we fall back to a permissive schema). */
+    inputConversionFailed: boolean;
+    outputConversionFailed: boolean;
+}
+/**
+ * Return compiled input/output schemas for one operation, building (and
+ * caching) on first access. Subsequent calls within the same bundleVersion
+ * return the cached pair.
+ */
+export declare function getCompiledOpSchemas(args: {
+    bundleVersion: string;
+    operationId: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+}): CompiledOpSchemas;
+/**
+ * Test/maintenance helper: drop entries whose bundleVersion is no longer
+ * referenced by any active bundle. v1.2.0 calls this opportunistically on
+ * bundle swap; in practice the cache stays small (one entry per op per
+ * version) and the GC isn't strictly necessary.
+ */
+export declare function dropEntriesForBundleVersion(bundleVersion: string): number;
+/** Reset the entire cache. Used by tests. */
+export declare function clearCompiledSchemaCache(): void;
+//# sourceMappingURL=schema-cache.d.ts.map

package/executor/schema-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-cache.d.ts","sourceRoot":"","sources":["../../src/executor/schema-cache.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAC;AAEvC,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,UAAU,CAAC;AAE1C,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,EAAE,cAAc,CAAC;IACvB,6FAA6F;IAC7F,qBAAqB,EAAE,OAAO,CAAC;IAC/B,sBAAsB,EAAE,OAAO,CAAC;CACjC;AAmCD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC,GAAG,iBAAiB,CAepB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAUzE;AAED,6CAA6C;AAC7C,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}

package/executor/ssrf-guard.d.ts

@@ -0,0 +1,16 @@
+import type { OutboundOptions } from '../skilled-openapi.types';
+export interface SsrfCheckResult {
+    ok: boolean;
+    reason?: string;
+}
+export declare function isPrivateIPv4(ip: string): boolean;
+export declare function isPrivateIPv6(ip: string): boolean;
+/**
+ * Validate an outbound URL against the allowlist + scheme rules + IP blocklist.
+ *
+ * @param target - The target URL (post path/query interpolation).
+ * @param allowedHosts - Set of hostnames declared by the active bundle's services.
+ * @param outbound - Plugin's outbound options (allowHttp, allowPrivateNetworks).
+ */
+export declare function checkOutboundUrl(target: string, allowedHosts: ReadonlySet<string>, outbound: OutboundOptions): Promise<SsrfCheckResult>;
+//# sourceMappingURL=ssrf-guard.d.ts.map

package/executor/ssrf-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-guard.d.ts","sourceRoot":"","sources":["../../src/executor/ssrf-guard.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAyBD,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAQjD;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAWjD;AAID;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,EACjC,QAAQ,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,CAAC,CA2C1B"}

package/index.d.ts

@@ -0,0 +1,7 @@
+import SkilledOpenApiPlugin from './skilled-openapi.plugin';
+export { SkilledOpenApiPlugin };
+export default SkilledOpenApiPlugin;
+export { skilledOpenApiPluginOptionsSchema } from './skilled-openapi.types';
+export type { SkilledOpenApiPluginOptions, SkilledOpenApiPluginOptionsInput, BundleSourceOptions, StaticSourceOptions, NpmSourceOptions, SaasSourceOptions, SignatureKey, OutboundOptions, } from './skilled-openapi.types';
+export { SkilledOpenApiConfig, SkilledOpenApiCredentialResolver } from './skilled-openapi.symbols';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,oBAAoB,MAAM,0BAA0B,CAAC;AAE5D,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAChC,eAAe,oBAAoB,CAAC;AAEpC,OAAO,EAAE,iCAAiC,EAAE,MAAM,yBAAyB,CAAC;AAC5E,YAAY,EACV,2BAA2B,EAC3B,gCAAgC,EAChC,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,eAAe,GAChB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,oBAAoB,EAAE,gCAAgC,EAAE,MAAM,2BAA2B,CAAC"}