@mcp-index/sdk 0.1.0

package/dist/src/gate.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The shared GATE core — the pure pre-flight decision, decoupled from any I/O
+ * seam. A faithful port of Python `tooling/cse/gate.py`. Pin TOFU, derive the
+ * live contract hash, compare to the pin, and on drift VALIDATE -> DECIDE
+ * (benign auto-accept / behavioral-mandated INCONCLUSIVE / HOLD), then apply the
+ * per-server POSTURE. NO credential, NO transport, NO network: the Gate reads
+ * only the PUBLIC contract dict the caller observed.
+ */
+import { PreflightPin } from "./preflight.js";
+import type { PinnedTool, PreflightVerdict, ToolDef } from "./preflight.js";
+import { ChangeKind, isSafetyRelevant } from "./schemaDiff.js";
+import { ErrorStore, Operation } from "./errors.js";
+declare const DEFAULT_BEHAVIORAL_MANDATED_KINDS: ReadonlySet<ChangeKind>;
+export declare enum Posture {
+    MONITOR = "monitor",
+    GUARD = "guard",
+    STRICT = "strict"
+}
+export declare const HELD_PROVENANCE_UNAVAILABLE_BANNER = "\u2B21 mcpindex \u2014 held a call before your agent ran it (provenance unavailable; no detail shown).";
+export declare const INTERNAL_ERROR_HELD_MESSAGE = "\u2B21 mcpindex internal error \u2014 held this call for safety. [Override]";
+export declare function isInternalErrorVerdict(verdict: PreflightVerdict): boolean;
+export declare function internalErrorHold(serverId: string, toolName: string): PreflightVerdict;
+export declare enum Ownership {
+    OSS = "oss",
+    DEV_OWNED = "dev_owned",
+    UNOWNED_THIRD_PARTY = "unowned_third_party"
+}
+export declare enum BehavioralMethod {
+    SANDBOX_BATTERY = "sandbox_battery",
+    READ_ONLY_PROBE = "read_only_probe",
+    DECLINED = "declined"
+}
+export declare function chooseBehavioralMethod(ownership: Ownership): BehavioralMethod;
+export declare enum BehavioralOutcome {
+    CLEARED = "cleared",
+    FAILED = "failed",
+    UNAVAILABLE = "unavailable",
+    DECLINED = "declined"
+}
+/**
+ * True IFF the verifier ACTUALLY observed the tool's behaviour (CLEARED or FAILED).
+ * UNAVAILABLE / DECLINED / null (verifier never consulted) all mean behaviour did NOT run, so
+ * the evidence tier floors to STRUCTURAL_ONLY (0) — never a false BEHAVIORAL/3 stamp. This is
+ * the ONE place tier-3 eligibility is decided, keyed on the structured enum, never on a
+ * verifier-controlled reason string. Python mirror: `Gate._behaviour_observed`.
+ */
+export declare function behaviourObserved(outcome: BehavioralOutcome | null): boolean;
+export interface BehavioralResult {
+    readonly outcome: BehavioralOutcome;
+    readonly method: BehavioralMethod;
+    readonly reason: string;
+}
+export interface BehavioralVerifier {
+    verify(serverId: string, toolName: string, toolDef: ToolDef, ownership: Ownership, method: BehavioralMethod): BehavioralResult;
+}
+export declare function renderHoldBanner(verdict: PreflightVerdict, monthlyCount?: number | null): string;
+export interface GateOptions {
+    pin: PreflightPin;
+    serverId: string;
+    failOpen?: boolean;
+    autoAcceptBenign?: boolean;
+    now?: () => string;
+    ownership?: Ownership;
+    behavioralMandatedKinds?: ReadonlySet<ChangeKind>;
+    verifier?: BehavioralVerifier | null;
+    posture?: Posture;
+    errors?: ErrorStore | null;
+}
+export declare class Gate {
+    private readonly pin;
+    private readonly _serverId;
+    private readonly failOpen;
+    private readonly autoAcceptBenign;
+    private readonly now;
+    private readonly _ownership;
+    private readonly behavioralMandatedKinds;
+    private readonly _verifier;
+    private readonly _posture;
+    private readonly errors;
+    constructor(opts: GateOptions);
+    get serverId(): string;
+    get posture(): Posture;
+    get verifier(): BehavioralVerifier | null;
+    get ownership(): Ownership;
+    pinFor(name: string): PinnedTool | null;
+    /** TOFU-pin one observed tool if not already pinned. */
+    observe(name: string, defn: ToolDef): void;
+    repinOne(name: string, observed: ToolDef): PinnedTool;
+    evaluate(name: string, observed: ToolDef | null): PreflightVerdict;
+    private classifyDrift;
+    private mandatedUnhashedDrift;
+    private validateDrift;
+    private riskEscalation;
+    private static riskOf;
+    private static markerIn;
+    private markerIn;
+    private descriptionHold;
+    private driftHold;
+    private behavioralInconclusive;
+    private holdOrFailopen;
+    applyPosture(stat: PreflightVerdict): PreflightVerdict;
+    decide(name: string, observed: ToolDef | null): [PreflightVerdict, PreflightVerdict];
+    internalErrorVerdict(name: string): PreflightVerdict;
+    captureError(exc: unknown, operation: Operation, ourCodeLocation: string): void;
+    private isUnambiguousDangerous;
+    private notifyOnly;
+    /**
+     * Verdict-only public wrapper. Callers that must DERIVE the evidence tier
+     * (`tierReached` / `verdictScope`) honestly use `runBehavioralOutcome`, which also surfaces
+     * the STRUCTURED `BehavioralOutcome` so the tier is keyed on the enum and NEVER on the
+     * verifier-controlled free-text reason string.
+     */
+    runBehavioral(toolName: string, observed: ToolDef | null, staticVerdict: PreflightVerdict, verifier: BehavioralVerifier): PreflightVerdict;
+    /**
+     * Like `runBehavioral`, but ALSO returns the structured `BehavioralOutcome` the verifier
+     * produced (or `null` when the verifier was NEVER consulted — a missing observed contract or
+     * a verifier that errored). Callers key the evidence tier on this enum, never on the reason
+     * string: behaviour was OBSERVED iff the outcome is CLEARED or FAILED; UNAVAILABLE / DECLINED
+     * / null mean behaviour did NOT run (tier 0). Keying on the enum closes a provenance-honesty
+     * hole — the reason string embeds the verifier-controlled `result.reason`, so a verifier
+     * returning UNAVAILABLE with a reason that merely CONTAINS the literal "behavioral validation
+     * FAILED" must NOT forge a BEHAVIORAL/tier-3 stamp on a HOLD where behaviour was never seen.
+     * Python mirror: `Gate.run_behavioral_outcome`.
+     */
+    runBehavioralOutcome(toolName: string, observed: ToolDef | null, staticVerdict: PreflightVerdict, verifier: BehavioralVerifier): [PreflightVerdict, BehavioralOutcome | null];
+}
+export { isSafetyRelevant, DEFAULT_BEHAVIORAL_MANDATED_KINDS };
+//# sourceMappingURL=gate.d.ts.map

package/dist/src/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/gate.ts"],"names":[],"mappings":"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"}