@mcp-index/sdk 0.18.1 → 0.19.0

package/dist/src/lock/signing.js

@@ -0,0 +1,85 @@
+/**
+ * Manifest signature verification (section 8.2).
+ *
+ * The signer identity and the trust root come from the host's own config
+ * object. Nothing here reads the lock repository or the environment for
+ * either. `sigstore` is an optional peer dependency, loaded on the verify
+ * path only; when it is missing, verify returns false and the reader fails
+ * with lock-signature-invalid, as it does for a missing or bad bundle.
+ *
+ * Verification is offline against a trusted_root.json the operator supplies.
+ * The issuer and SAN are matched exactly: sigstore treats the SAN policy as a
+ * regular expression, so it gets an escaped, anchored pattern, and the signer
+ * it returns is compared again by plain string equality.
+ */
+import { lstatSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+}
+/** Exact, anchored pattern for sigstore's regex-based SAN policy. */
+export function anchoredPattern(text) {
+    return `^${escapeRegExp(text)}$`;
+}
+function readTrustedRoot(path) {
+    const st = lstatSync(path);
+    if (st.isSymbolicLink() || !st.isFile())
+        throw new Error("trusted root is not a regular file");
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function defaultLoader() {
+    const here = createRequire(import.meta.url);
+    // Resolve the @sigstore/* parts from sigstore's own location, so this works
+    // whether or not the package manager hoists them.
+    const main = here.resolve("sigstore");
+    const fromSigstore = createRequire(main);
+    return (name) => (name === "sigstore" ? here(main) : fromSigstore(name));
+}
+function loadParts(load) {
+    load("sigstore"); // presence check for the declared peer
+    const verify = load("@sigstore/verify");
+    const bundle = load("@sigstore/bundle");
+    const specs = load("@sigstore/protobuf-specs");
+    return {
+        bundleFromJSON: bundle.bundleFromJSON,
+        toSignedEntity: verify.toSignedEntity,
+        toTrustMaterial: verify.toTrustMaterial,
+        Verifier: verify.Verifier,
+        TrustedRoot: specs.TrustedRoot,
+    };
+}
+/**
+ * Sigstore verifier for MANIFEST.json. Returns false (never throws) on a
+ * missing module, unreadable trust root, malformed bundle, failed signature,
+ * or a signer that differs from the configured issuer and SAN.
+ */
+export function sigstoreVerifier(options) {
+    return {
+        async verify(manifest, bundle, signer) {
+            try {
+                if (typeof signer.issuer !== "string" || typeof signer.san !== "string" || !signer.issuer || !signer.san) {
+                    return false;
+                }
+                const parts = loadParts(options.load ?? defaultLoader());
+                const root = parts.TrustedRoot.fromJSON(readTrustedRoot(options.trustedRootPath));
+                const trust = parts.toTrustMaterial(root);
+                const verifier = new parts.Verifier(trust, {
+                    tlogThreshold: options.tlogThreshold ?? 1,
+                    ctlogThreshold: options.ctlogThreshold ?? 1,
+                });
+                const parsed = parts.bundleFromJSON(JSON.parse(Buffer.from(bundle).toString("utf8")));
+                const entity = parts.toSignedEntity(parsed, Buffer.from(manifest));
+                const result = verifier.verify(entity, {
+                    subjectAlternativeName: anchoredPattern(signer.san),
+                    extensions: { issuer: signer.issuer },
+                });
+                const identity = result?.identity;
+                return identity?.subjectAlternativeName === signer.san && identity?.extensions?.issuer === signer.issuer;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+//# sourceMappingURL=signing.js.map

package/dist/src/lock/signing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.js","sourceRoot":"","sources":["../../../src/lock/signing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAiB5C,SAAS,YAAY,CAAC,IAAY;IAChC,OAAO,IAAI,CAAC,OAAO,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAC;AACtD,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC;AACnC,CAAC;AAED,SAAS,eAAe,CAAC,IAAY;IACnC,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,EAAE,CAAC,cAAc,EAAE,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IAC/F,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAY,CAAC;AAC3D,CAAC;AAED,SAAS,aAAa;IACpB,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5C,4EAA4E;IAC5E,kDAAkD;IAClD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACtC,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACzC,OAAO,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;AACnF,CAAC;AAcD,SAAS,SAAS,CAAC,IAA+B;IAChD,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,uCAAuC;IACzD,MAAM,MAAM,GAAG,IAAI,CAAC,kBAAkB,CAA4B,CAAC;IACnE,MAAM,MAAM,GAAG,IAAI,CAAC,kBAAkB,CAA4B,CAAC;IACnE,MAAM,KAAK,GAAG,IAAI,CAAC,0BAA0B,CAA4B,CAAC;IAC1E,OAAO;QACL,cAAc,EAAE,MAAM,CAAC,cAAiD;QACxE,cAAc,EAAE,MAAM,CAAC,cAAiD;QACxE,eAAe,EAAE,MAAM,CAAC,eAAmD;QAC3E,QAAQ,EAAE,MAAM,CAAC,QAAqC;QACtD,WAAW,EAAE,KAAK,CAAC,WAA2C;KAC/D,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgC;IAC/D,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,QAAoB,EAAE,MAAkB,EAAE,MAAsB;YAC3E,IAAI,CAAC;gBACH,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;oBACzG,OAAO,KAAK,CAAC;gBACf,CAAC;gBACD,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,IAAI,aAAa,EAAE,CAAC,CAAC;gBACzD,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW,CAAC,QAAQ,CAAC,eAAe,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;gBAClF,MAAM,KAAK,GAAG,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;gBAC1C,MAAM,QAAQ,GAAG,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE;oBACzC,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,CAAC;oBACzC,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,CAAC;iBAC5C,CAAC,CAAC;gBACH,MAAM,MAAM,GAAG,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAY,CAAC,CAAC;gBACjG,MAAM,MAAM,GAAG,KAAK,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;gBACnE,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;oBACrC,sBAAsB,EAAE,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC;oBACnD,UAAU,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;iBACtC,CAAC,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,EAAE,QAAQ,CAAC;gBAClC,OAAO,QAAQ,EAAE,sBAAsB,KAAK,MAAM,CAAC,GAAG,IAAI,QAAQ,EAAE,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC;YAC3G,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/lock/store.d.ts

@@ -0,0 +1,149 @@
+/**
+ * LockStore: where a host gets its lock snapshot and where approvals land.
+ *
+ * A snapshot is frozen and carries a snapshotId, so a decision can name the
+ * lock state it came from. loadSnapshot never throws for a bad lock: a lock
+ * failure comes back as a LockError inside the snapshot, and the check then
+ * withholds everything. It may throw when the store itself cannot be reached;
+ * hosts treat that as lock-unreadable.
+ *
+ * The file store reads `.mcp/` once per load (see lock.ts). Approvals and
+ * revocations take the existing create-excl file lock on `.mcp/lock.lck`
+ * (fileLock.ts), write the contract, then replace the shard (and the manifest,
+ * when one exists) by rename from a temporary file in `.mcp/`, so `.mcp/lock`
+ * never holds a partial file.
+ */
+import { LockError } from "./lock.js";
+import type { Approval, Identity, Lock, ManifestVerifier, SignerIdentity, Via } from "./lock.js";
+export interface LockSnapshot {
+    readonly snapshotId: string;
+    /** Epoch ms when the store produced this snapshot. */
+    readonly loadedAt: number;
+    readonly lock: Lock | LockError;
+}
+interface ApprovalCommon {
+    readonly identity: Identity;
+    /** Who approved. A database store records its authenticated principal instead. */
+    readonly subject?: string;
+    readonly via: Via;
+    readonly ref?: string;
+    /** RFC 3339; defaults to now, to the second. */
+    readonly at?: string;
+}
+/** Approve one tool: `tool` is the raw Tool object as served (JSON.parse output). */
+export type ApproveToolRequest = ApprovalCommon & {
+    readonly tool: unknown;
+};
+/** Approve the server's instructions text. */
+export type ApproveInstructionsRequest = ApprovalCommon & {
+    readonly instructions: string;
+};
+export type ApproveRequest = ApproveToolRequest | ApproveInstructionsRequest;
+export type RevokeRequest = {
+    readonly identity: Identity;
+    readonly tool: string;
+} | {
+    readonly identity: Identity;
+    readonly instructions: true;
+};
+export interface LockStore {
+    loadSnapshot(): Promise<LockSnapshot>;
+    approve(request: ApproveRequest): Promise<void>;
+    revoke(request: RevokeRequest): Promise<void>;
+}
+export declare function nowRfc3339(date?: Date): string;
+export declare function snapshotOfError(error: LockError, loadedAt?: number): LockSnapshot;
+/** What an approval writes: digest, contract bytes and contract filename. */
+export interface PreparedTool {
+    readonly name: string;
+    readonly digest: string;
+    readonly contract: string;
+    readonly body: Buffer;
+    /** Digest of the served top-level `_meta`, when the tool has one with a digest. */
+    readonly metaDigest: string | null;
+}
+export declare function prepareTool(tool: unknown): PreparedTool;
+export declare function checkApprovalFields(request: ApprovalCommon, subject: string): Approval;
+/**
+ * Where a host keeps the highest manifest (or head) sequence it accepted, so
+ * a rollback is refused across restarts (section 8.2 step 3). `read` returns
+ * null when nothing was recorded yet and throws when the record is unusable.
+ */
+export interface SequenceStore {
+    read(): number | null;
+    write(sequence: number): void;
+}
+/**
+ * A host-owned file holding the sequence as ASCII digits and a newline, the
+ * format the Python host writes to its sequence_path. A missing file is no
+ * record; a file that is not a regular file or does not hold digits throws.
+ */
+export declare function fileSequenceStore(path: string): SequenceStore;
+/** A host configuration the host must not run with. Thrown when a store is constructed. */
+export declare class HostConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Where the system puts a host path: realpath of its longest existing part
+ * with the rest appended. FileLockStore opens this form, so the file it
+ * writes is the one hostPathProblem checked.
+ */
+export declare function resolvedHostPath(value: string): string;
+/**
+ * The repository that holds the lock (section 8.2, draft 1e), walking up
+ * from the resolved lock root. A `.git` directory ends the walk, and so does
+ * a `.git` file pointing into a git directory's `worktrees/` (a linked
+ * worktree's top). Any other `.git` file, a submodule's or one that names
+ * neither, is a candidate: the walk goes on so a submodule resolves to its
+ * superproject, and the candidate stands when nothing above has a `.git`
+ * entry. With no entry at all the repository is the lock root, and only the
+ * lock root is protected.
+ */
+export declare function repositoryRoot(lockRoot: string): string;
+/**
+ * Null if every named host path lies outside the repository that holds the
+ * lock and the lock root, else what is wrong. Inside means an existing
+ * leading part of the path as given, or an ancestor of its resolved form, is
+ * the same directory (device and inode) as the repository root or the lock
+ * root.
+ */
+export declare function hostPathProblem(lockRoot: string, paths: Readonly<Record<string, string | null | undefined>>): string | null;
+export interface FileLockStoreOptions {
+    /** Lock root: the directory that contains `.mcp/`. */
+    readonly root: string;
+    readonly requireManifest?: boolean;
+    /**
+     * From host configuration only. With a signer set, every load verifies
+     * MANIFEST.json, and the host must also name a sequence store
+     * (sequencePath or sequenceStore); without one every load is
+     * lock-signature-invalid.
+     */
+    readonly signer?: SignerIdentity | null;
+    readonly verifier?: ManifestVerifier | null;
+    /**
+     * Sigstore trusted_root.json from host configuration. Without `verifier`,
+     * the store verifies with sigstoreVerifier over this file. It must lie
+     * outside the repository that holds the lock (section 8.2).
+     */
+    readonly trustedRootPath?: string;
+    /**
+     * Host-owned file for the last accepted sequence (see fileSequenceStore).
+     * It must lie outside the repository that holds the lock.
+     */
+    readonly sequencePath?: string;
+    /** Or any other place the host keeps it. Takes precedence over sequencePath. */
+    readonly sequenceStore?: SequenceStore;
+    readonly now?: () => number;
+}
+/** The higher of two sequence floors; null only when both are. */
+export declare function sequenceFloor(a: number | null, b: number | null): number | null;
+export declare class FileLockStore implements LockStore {
+    #private;
+    /** Throws HostConfigError when sequencePath or trustedRootPath lies inside the lock's repository. */
+    constructor(options: FileLockStoreOptions);
+    loadSnapshot(): Promise<LockSnapshot>;
+    approve(request: ApproveRequest): Promise<void>;
+    revoke(request: RevokeRequest): Promise<void>;
+}
+export {};
+//# sourceMappingURL=store.d.ts.map

package/dist/src/lock/store.d.ts.map

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