@sezzlee/sdk-nestjs 0.0.0-stage → 0.2.0

package/dist/visibility/evaluator.d.ts

@@ -0,0 +1,8 @@
+import type { CallerFacts } from "@sezzlee/core";
+import type { OuterRequest } from "../options.js";
+export interface VisibilityEvaluator {
+    resolve(outer: OuterRequest | undefined, policyNames: ReadonlySet<string>): Promise<CallerFacts>;
+}
+export declare class DeclarativeVisibilityEvaluator implements VisibilityEvaluator {
+    resolve(): Promise<CallerFacts>;
+}

package/dist/visibility/evaluator.js

@@ -0,0 +1,5 @@
+export class DeclarativeVisibilityEvaluator {
+    resolve() {
+        return Promise.resolve({ identity: "unknown" });
+    }
+}

package/dist/visibility/probe.d.ts

@@ -0,0 +1,25 @@
+import { type CallHandler, type ExecutionContext, type NestInterceptor } from "@nestjs/common";
+import { type Observable } from "rxjs";
+import type { VisibilityDecision } from "@sezzlee/core";
+import type { CatalogEntry } from "../catalog.js";
+import { SezzleeDispatcher } from "../dispatcher.js";
+import { wasShortCircuited } from "../markers.js";
+import type { OuterRequest, SezzleeOptions } from "../options.js";
+export declare class SezzleeProbeInterceptor implements NestInterceptor {
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+export interface ProbeEvaluator {
+    canProbe(entry: CatalogEntry): boolean;
+    probe(entry: CatalogEntry, outer: OuterRequest | undefined): Promise<VisibilityDecision>;
+}
+export declare class SezzleeProbeEvaluator implements ProbeEvaluator {
+    private readonly dispatcher;
+    private readonly options;
+    private readonly disabled;
+    constructor(dispatcher: SezzleeDispatcher, options: SezzleeOptions);
+    clearDisabled(): void;
+    canProbe(entry: CatalogEntry): boolean;
+    probe(entry: CatalogEntry, outer: OuterRequest | undefined): Promise<VisibilityDecision>;
+    private pathFor;
+}
+export { wasShortCircuited };

package/dist/visibility/probe.js

@@ -0,0 +1,104 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Injectable, } from "@nestjs/common";
+import { of } from "rxjs";
+import { SezzleeDispatchAborted } from "../synthetic-context.js";
+import { isSezzleeProbe, markShortCircuited, wasShortCircuited, } from "../markers.js";
+let SezzleeProbeInterceptor = class SezzleeProbeInterceptor {
+    intercept(context, next) {
+        const request = context.switchToHttp().getRequest();
+        if (!isSezzleeProbe(request)) {
+            return next.handle();
+        }
+        markShortCircuited(request);
+        return of(undefined);
+    }
+};
+SezzleeProbeInterceptor = __decorate([
+    Injectable()
+], SezzleeProbeInterceptor);
+export { SezzleeProbeInterceptor };
+export class SezzleeProbeEvaluator {
+    dispatcher;
+    options;
+    disabled = new Map();
+    constructor(dispatcher, options) {
+        this.dispatcher = dispatcher;
+        this.options = options;
+    }
+    clearDisabled() {
+        this.disabled.clear();
+    }
+    canProbe(entry) {
+        return entry.template !== undefined && !this.disabled.has(entry.tool.name);
+    }
+    async probe(entry, outer) {
+        const path = this.pathFor(entry);
+        let result;
+        try {
+            result = await this.dispatcher.probe(entry.descriptor.method, path, outer);
+        }
+        catch (error) {
+            if (!(error instanceof SezzleeDispatchAborted)) {
+                throw error;
+            }
+            this.disabled.set(entry.tool.name, "the probe was abandoned before the pipeline produced a response");
+            return "unknown";
+        }
+        if (result.status === 401 || result.status === 403) {
+            return "deny";
+        }
+        if (result.shortCircuited && result.status < 400) {
+            return "allow";
+        }
+        this.disabled.set(entry.tool.name, result.status === 404
+            ? "the probe path did not route; declare a value in visibility.probeValues"
+            : "the response came back without the short-circuit marker");
+        return "unknown";
+    }
+    pathFor(entry) {
+        return entry.descriptor.route.replaceAll(/\{([^}]+)\}/g, (_match, name) => encodeURIComponent(constantFor(entry, name) ??
+            this.options.visibility.probeValues.get(name.toLowerCase()) ??
+            placeholderFor(entry, name)));
+    }
+}
+/**
+ * Guard: a family member is reachable only through its own key, so a placeholder or a host probe
+ * value would probe a different member, or none, and report its verdict for this one.
+ */
+function constantFor(entry, name) {
+    const fill = entry.template?.parameters.find((parameter) => parameter.name === name && parameter.location === "path")?.fill;
+    if (fill?.kind !== "constant") {
+        return undefined;
+    }
+    const value = fill.value;
+    return typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean"
+        ? String(value)
+        : undefined;
+}
+function placeholderFor(entry, name) {
+    const parameter = entry.descriptor.parameters?.find((candidate) => candidate.name === name && candidate.in === "path");
+    switch (parameter?.schema.type) {
+        case "integer":
+        case "number":
+            return "1";
+        case "boolean":
+            return "true";
+        default:
+            break;
+    }
+    if (parameter?.schema.format === "uuid") {
+        return "00000000-0000-0000-0000-000000000000";
+    }
+    if (parameter?.schema.format === "date-time") {
+        return "2000-01-01";
+    }
+    return "probe";
+}
+export { wasShortCircuited };

package/dist/visibility/provider.d.ts

@@ -0,0 +1,23 @@
+import { type CallerFacts, type CallerScope, type SezzleeCache, type VisibilityDecision } from "@sezzlee/core";
+import type { CatalogEntry } from "../catalog.js";
+import type { OuterRequest, SezzleeOptions } from "../options.js";
+import type { ProbeEvaluator } from "./probe.js";
+import type { VisibilityEvaluator } from "./evaluator.js";
+export declare class CallerVisibilityProvider {
+    private readonly evaluator;
+    private readonly prober;
+    private readonly cache;
+    private readonly options;
+    private readonly factsFlight;
+    private readonly probeFlight;
+    private epoch;
+    constructor(evaluator: VisibilityEvaluator, prober: ProbeEvaluator, cache: SezzleeCache, options: SezzleeOptions);
+    bump(): void;
+    canProbe(entry: CatalogEntry): boolean;
+    facts(scope: CallerScope, outer: OuterRequest | undefined, policyNames: ReadonlySet<string>): Promise<CallerFacts>;
+    probe(scope: CallerScope, entry: CatalogEntry, outer: OuterRequest | undefined): Promise<VisibilityDecision>;
+    decide(auth: CatalogEntry["descriptor"]["auth"], facts: CallerFacts): VisibilityDecision;
+    visible(decision: VisibilityDecision): boolean;
+    private read;
+    private write;
+}

package/dist/visibility/provider.js

@@ -0,0 +1,118 @@
+import { evaluateVisibility, SingleFlight, } from "@sezzlee/core";
+export class CallerVisibilityProvider {
+    evaluator;
+    prober;
+    cache;
+    options;
+    factsFlight = new SingleFlight();
+    probeFlight = new SingleFlight();
+    epoch = 0;
+    constructor(evaluator, prober, cache, options) {
+        this.evaluator = evaluator;
+        this.prober = prober;
+        this.cache = cache;
+        this.options = options;
+    }
+    bump() {
+        this.epoch += 1;
+    }
+    canProbe(entry) {
+        return this.prober.canProbe(entry);
+    }
+    async facts(scope, outer, policyNames) {
+        if (this.options.cache.lifetimeMs <= 0) {
+            return this.evaluator.resolve(outer, policyNames);
+        }
+        const key = { scope, kind: "facts" };
+        const observed = this.epoch;
+        const cached = await this.read(key);
+        if (cached !== undefined) {
+            return decodeFacts(cached);
+        }
+        const resolved = await this.factsFlight.run(String(scope.key), () => this.evaluator.resolve(outer, policyNames));
+        if (observed === this.epoch) {
+            await this.write(key, encodeFacts(resolved));
+        }
+        return resolved;
+    }
+    async probe(scope, entry, outer) {
+        const key = { scope, kind: "probe", subkey: entry.tool.name };
+        if (this.options.cache.lifetimeMs <= 0) {
+            return this.prober.probe(entry, outer);
+        }
+        const observed = this.epoch;
+        const cached = await this.read(key);
+        if (cached === "A") {
+            return "allow";
+        }
+        if (cached === "D") {
+            return "deny";
+        }
+        const decision = await this.probeFlight.run(`${scope.key}:${entry.tool.name}`, () => this.prober.probe(entry, outer));
+        if (decision !== "unknown" && observed === this.epoch) {
+            await this.write(key, decision === "allow" ? "A" : "D");
+        }
+        return decision;
+    }
+    decide(auth, facts) {
+        return evaluateVisibility(auth, facts);
+    }
+    visible(decision) {
+        if (decision === "allow") {
+            return true;
+        }
+        if (decision === "deny") {
+            return false;
+        }
+        return this.options.visibility.onUnknown === "show";
+    }
+    async read(key) {
+        try {
+            return await this.cache.get(key);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async write(key, value) {
+        try {
+            await this.cache.set(key, value);
+        }
+        catch {
+            return;
+        }
+    }
+}
+function encodeFacts(facts) {
+    const identity = facts.identity === "present"
+        ? "P"
+        : facts.identity === "absent"
+            ? "A"
+            : "U";
+    const results = Object.entries(facts.policyResults ?? {})
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([name, decision]) => `${name}=${decision.charAt(0).toUpperCase()}`)
+        .join(";");
+    return `${identity}|${results}`;
+}
+function decodeFacts(encoded) {
+    const [identityCode, results = ""] = encoded.split("|");
+    const identity = identityCode === "P"
+        ? "present"
+        : identityCode === "A"
+            ? "absent"
+            : "unknown";
+    const policyResults = {};
+    for (const pair of results.split(";")) {
+        if (pair.length === 0) {
+            continue;
+        }
+        const [name, code] = pair.split("=");
+        if (name === undefined || code === undefined) {
+            continue;
+        }
+        policyResults[name] =
+            code === "A" ? "allow" : code === "D" ? "deny" : "unknown";
+    }
+    return { identity, policyResults };
+}

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "@sezzlee/sdk-nestjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Embeds an MCP layer into an existing NestJS backend: search-first tool discovery over your real endpoints, dispatched through your own guards, pipes and interceptors.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "nestjs",
+    "sezzlee",
+    "agents",
+    "ai",
+    "llm",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sezzlee/mcp.git",
+    "directory": "sdks/nestjs"
+  },
+  "homepage": "https://github.com/sezzlee/mcp/tree/main/sdks/nestjs#readme",
+  "bugs": {
+    "url": "https://github.com/sezzlee/mcp/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@sezzlee/core": "^0.2.0"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/express": ">=2.0.0",
+    "@modelcontextprotocol/node": ">=2.0.0",
+    "@modelcontextprotocol/server": ">=2.0.0",
+    "@nestjs/common": ">=10",
+    "@nestjs/core": ">=10",
+    "@types/express": ">=4",
+    "class-transformer": ">=0.5",
+    "class-validator": ">=0.14",
+    "rxjs": "^7.1.0",
+    "zod": "^4.5.4"
+  },
+  "peerDependenciesMeta": {
+    "@types/express": {
+      "optional": true
+    },
+    "class-transformer": {
+      "optional": true
+    },
+    "class-validator": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/express": "2.0.0",
+    "@modelcontextprotocol/node": "2.0.0",
+    "@modelcontextprotocol/server": "2.0.0",
+    "@nestjs/common": "^11.1.6",
+    "@nestjs/core": "^11.1.6",
+    "@nestjs/platform-express": "^11.1.6",
+    "@nestjs/testing": "^11.1.6",
+    "@sezzlee/oxlint-config": "0.0.0",
+    "@sezzlee/typescript-config": "0.0.0",
+    "@swc/core": "^1.13.0",
+    "@types/express": "^5.0.0",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/node": "^24.3.0",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.2",
+    "express": "^5.2.1",
+    "hono": "^4.11.4",
+    "jsonwebtoken": "^9.0.2",
+    "oxlint": "1.85.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "typescript": "7.0.2",
+    "unplugin-swc": "^1.5.5",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "lint": "oxlint --deny-warnings",
+    "check-types": "tsc -p tsconfig.test.json",
+    "test": "vitest run"
+  }
 }