@valbuild/mcp 0.123.0

package/dist/declarations/src/tools/writePath.d.ts

@@ -0,0 +1,160 @@
+import type { ModuleFilePath, PatchId } from "@valbuild/core";
+import { type Patch, type ParentRef } from "@valbuild/core/patch";
+import type { PatchAnalysis, ValOps } from "@valbuild/server";
+import type { ValToolDeps, ValToolState } from "./defineTool.js";
+import type { ValToolError } from "./types.js";
+/**
+ * A patch id, minted before the write is attempted.
+ *
+ * Same shape the Studio mints (a v4 UUID), and minting one that never gets used
+ * costs nothing — ids are not registered anywhere until a patch carries them.
+ */
+export declare function mintPatchId(): PatchId;
+/**
+ * What the new patch should hang off.
+ *
+ * The last known patch if there is one, otherwise the current head. Note the
+ * asymmetry between the two backends: `ValOpsFS` ignores `parentRef` entirely
+ * because its append-only ordering log defines order, while `ValOpsHttp` sends
+ * it up as `parentPatchId` for optimistic concurrency. So a wrong value here is
+ * invisible locally and a conflict in production — which is why this is derived
+ * fresh rather than remembered.
+ */
+export declare function deriveParentRef(ops: ValOps, patches: {
+    patches: readonly {
+        patchId: PatchId;
+    }[];
+}): Promise<ParentRef>;
+/**
+ * Would this patch leave the content valid?
+ *
+ * Applied to a **clone** of the sources, never the real ones: `applyPatch`
+ * mutates the document it is given, and ValOps carries a standing note that
+ * add operations misbehave without a clone. Validating in place would corrupt
+ * the sources every later call in this process reads.
+ *
+ * Server-side this is strictly better than the Studio's speculative check.
+ * `getSchemas()` returns real `Schema` instances, so the user's own `validate`
+ * closures run — and those are not carried by the serialized schema the browser
+ * has, which means the browser cannot run them at all.
+ */
+export declare function validateSpeculatively(ops: ValOps, state: ValToolState, moduleFilePath: ModuleFilePath, patch: Patch, 
+/** Bytes already staged for the patch this validates — see {@link PendingFiles}. */
+pendingFiles?: PendingFiles): Promise<{
+    status: "valid";
+}
+/** Applicable, but the result would not be publishable. */
+ | {
+    status: "invalid";
+    errors: string;
+}
+/** The patch does not fit the content at all, so there is nothing to judge. */
+ | {
+    status: "unapplicable";
+    result: ValToolError;
+}>;
+/**
+ * What to do when the change would leave the content invalid.
+ *
+ * `"reject"` for a tool that is editing existing content: an agent should not be
+ * able to break a site, and a rejected patch stores nothing.
+ *
+ * `"report"` for a tool whose whole purpose is to create something incomplete.
+ * `empty_at_path` scaffolds an entry the caller is then expected to fill in, so
+ * on most real schemas — anything with a non-empty string — the value it creates
+ * is invalid by construction. Rejecting that would make the tool useless on
+ * exactly the schemas it exists for, so instead the patch is saved and the
+ * remaining errors come back as a to-do list. This mirrors the Studio, where
+ * creating an empty entry is normal and the errors show until it is filled in.
+ */
+export type OnInvalid = "reject" | "report";
+/**
+ * Put the bytes a `file` op refers to where the patch can find them.
+ *
+ * Called with the ids the patch is about to be written under, because that is
+ * the whole reason this is a hook rather than something the caller does first:
+ * an upload is keyed by the patch id, and the patch id is minted here — once
+ * per attempt, so a conflict retry uploads under the id that actually lands
+ * rather than orphaning the bytes under the one that did not.
+ *
+ * Uploads run BEFORE `createPatch`, which is the order the Studio uses and the
+ * only one that works: a `file` op carries a hash, not data, so a patch stored
+ * before its bytes points at nothing, and a reader that arrives in between sees
+ * a broken image rather than a missing one.
+ */
+export type UploadPatchFiles = (input: {
+    patchId: PatchId;
+    parentRef: ParentRef;
+}) => Promise<{
+    status: "ok";
+    /**
+     * Which files this upload put where, keyed by the path the source refers
+     * to — the same shape `PatchAnalysis.fileLastUpdatedByPatchId` has.
+     *
+     * Handed back rather than assumed, because speculative validation reads
+     * exactly this to decide where a file's bytes are. Without it the check
+     * looks for the new image on disk, does not find it, and rejects the very
+     * write that was about to put it there.
+     */
+    files: PendingFiles;
+} | {
+    status: "error";
+    result: ValToolError;
+}>;
+/**
+ * Files uploaded for a patch that does not exist yet.
+ *
+ * Deliberately the analysis's own type rather than a lookalike: the whole point
+ * is that these merge over `fileLastUpdatedByPatchId`, and a second shape that
+ * happens to fit today would drift the first time a field is added there.
+ */
+export type PendingFiles = PatchAnalysis["fileLastUpdatedByPatchId"];
+export type SavePatchOptions = {
+    onInvalid?: OnInvalid;
+    uploadFiles?: UploadPatchFiles;
+};
+/**
+ * What a successful write reports back.
+ *
+ * Named, rather than left as the `Json` that `ValToolResult` widens it to, so
+ * that a tool building on `savePatch` — the image tool adds its own fields to
+ * this — can spread it without re-narrowing `Json` and without an assertion.
+ */
+export type SavePatchData = {
+    patchId: PatchId;
+    moduleFilePath: ModuleFilePath;
+    createdAt: string;
+    /**
+     * Always present, so a caller does not have to tell "absent" from "nothing
+     * left to do" to know whether the content is publishable.
+     */
+    unresolvedValidationErrors: string | null;
+};
+export type SavePatchResult = {
+    status: "ok";
+    data: SavePatchData;
+} | ValToolError;
+/**
+ * Upload, validate, then save — and retry once if someone else got there first.
+ *
+ * The retry exists because the parent ref is derived from a read that happened
+ * before the write. A conflict means the chain moved underneath us, and
+ * re-deriving is usually enough. Once only: a loop here would be an agent
+ * fighting a human editor in the Studio, and losing slowly is worse than
+ * failing clearly.
+ *
+ * The order of the first two is the part that is easy to get backwards. A
+ * patch's `file` op carries a hash, not bytes, so validation asks the store
+ * where those bytes are — and if they are not there yet, the check that was
+ * supposed to say "this image is fine" says "this image is missing" and rejects
+ * the write that would have uploaded it. So the bytes go up first, and the
+ * upload says where it put them.
+ *
+ * The cost is that a REJECTED write leaves an upload no patch refers to. That
+ * is a state the patch store already expects and already collects — see
+ * `dropStaleUploads` in `patchStore.ts`, which exists because a browser can
+ * abandon an upload the same way — so it is bounded rather than untidy, and it
+ * is the cheaper of the two failures by a distance: the other one is a write
+ * that cannot succeed at all.
+ */
+export declare function savePatch(deps: ValToolDeps, moduleFilePath: ModuleFilePath, patch: Patch, options?: SavePatchOptions): Promise<SavePatchResult>;

package/dist/declarations/src/valAccessToken.d.ts

@@ -0,0 +1,93 @@
+import { type ValToolAuth } from "./tools/index.js";
+/**
+ * Verifying an OAuth access token, which is the whole of what makes this app a
+ * resource server rather than a relay.
+ *
+ * The token is issued by Val's authorization server and presented by an MCP
+ * client. This app holds no signing key for it and cannot mint one — it fetches
+ * the issuer's *public* keys and checks a signature. That asymmetry is the
+ * point: a verified `sub` is a fact about the token rather than a claim by
+ * whoever sent it, which is what lets the tools attribute a patch to that
+ * profile at all.
+ *
+ * ## Why this is not `jose`
+ *
+ * `jose` was the first choice and was rejected on a fact rather than a
+ * preference: version 6 is ESM-only (`"type": "module"`, no CJS export). This
+ * package is built by preconstruct and `require`d by Next.js server code, so an
+ * ESM-only dependency here is a runtime failure in consumers' apps, not a build
+ * inconvenience. Adding it would also put a dependency in every install of
+ * `@valbuild/next` for one function.
+ *
+ * The actual cryptography is still not hand-rolled — `node:crypto` does the
+ * ECDSA and the JWK import. What is written here is the JWS envelope and the
+ * claim checks, and the rules that keep that safe are worth stating because
+ * this repository has already shipped the counterexample (`decodeJwt`: `exp`
+ * never checked, a non-constant-time compare, verification skippable):
+ *
+ * - **`alg` is pinned**, not read from the token. The header is only consulted
+ *   for `kid`. A verifier that honours the token's own `alg` can be handed
+ *   `HS256` and will treat the *published* public key as a shared secret.
+ * - **Nothing is read from the payload before the signature verifies.** Claims
+ *   from an unverified token are attacker input.
+ * - **Keys come only from the configured issuer's JWKS**, never from the token.
+ *   The key set is cached, but a token naming a `kid` the cache does not hold
+ *   provokes one rate-limited refetch rather than a refusal — see
+ *   {@link UNKNOWN_KID_REFETCH_INTERVAL_MS}. Without that, this server's own
+ *   cache turns any key rotation into an outage lasting the rest of the TTL.
+ * - **ECDSA JWS signatures are raw `r||s`** (RFC 7518), not DER, which is what
+ *   `dsaEncoding: "ieee-p1363"` below is for. Omit it and every valid signature
+ *   is rejected — or worse, a future change makes it accept the wrong thing.
+ */
+export type ValOAuthConfig = {
+    /**
+     * The authorization server, and therefore the expected `iss`.
+     *
+     * Also where the JWKS is fetched from, so it is the one value that decides
+     * which keys can produce a token this app accepts. Configuration, never
+     * request input — a request that could name its own issuer could name its own
+     * key.
+     */
+    issuer: string;
+    /**
+     * This endpoint's absolute URL, and therefore the expected `aud` (RFC 8707).
+     *
+     * Audience binding is what stops a token minted for one Val site being
+     * replayed against another: without it, any deployment the user has access to
+     * would accept a token issued for any other.
+     */
+    resource: string;
+    /**
+     * Clock skew allowance, in seconds.
+     *
+     * Servers disagree about the time by more than you would like, and a token
+     * refused for being a second early is indistinguishable, to the person using
+     * it, from a broken login.
+     */
+    clockToleranceSeconds?: number;
+    /** Test seam. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+};
+export type ValAccessTokenResult = {
+    status: "ok";
+    auth: Extract<ValToolAuth, {
+        type: "verified-profile";
+    }>;
+} | {
+    status: "refused";
+    /** For the `WWW-Authenticate` challenge: RFC 6750 section 3.1. */
+    error: "invalid_request" | "invalid_token" | "insufficient_scope";
+    description: string;
+};
+/** Test seam: a fresh process would have an empty cache anyway. */
+export declare function clearValAccessTokenCache(): void;
+/**
+ * Read `Authorization: Bearer …`.
+ *
+ * Exported because the refusal needs to know whether a token was presented at
+ * all: RFC 6750 distinguishes "no credential" — a bare `401`, which is an
+ * invitation to authenticate — from "a bad credential", and a client that gets
+ * the second when it deserved the first will not start the authorization flow.
+ */
+export declare function readBearerToken(request: Request): string | null;
+export declare function verifyValAccessToken(request: Request, config: ValOAuthConfig): Promise<ValAccessTokenResult>;

package/dist/declarations/src/valMcpMetadata.d.ts

@@ -0,0 +1,47 @@
+import type { ValOAuthConfig } from "./valAccessToken.js";
+/**
+ * The one document an MCP client needs before it can authorize: RFC 9728
+ * Protected Resource Metadata, served by the *resource* server.
+ *
+ * This is how a client discovers where to authorize. It asks the resource — this
+ * app — and the resource names its authorization server. Which is why this
+ * belongs here and the RFC 8414 *authorization server* metadata does not: that
+ * document lives at the issuer, describes the issuer's own endpoints, and is
+ * served by the issuer. An app serving a copy would be asserting the issuer's
+ * configuration on its behalf, and would be wrong the moment the issuer changed
+ * anything.
+ *
+ * The flow, so the split reads as a whole:
+ *
+ * 1. client → `{app}/api/mcp` with no token → `401` naming this document
+ * 2. client → `{app}/.well-known/oauth-protected-resource` → the issuer
+ * 3. client → `{issuer}/.well-known/oauth-authorization-server` → endpoints
+ * 4. client → issuer's `/authorize`, then `/token`
+ * 5. client → `{app}/api/mcp` with the token
+ */
+export type ValMcpMetadataHandlers = {
+    /** The metadata document. */
+    GET: (request: Request) => Response;
+    /**
+     * The CORS preflight.
+     *
+     * Required rather than defensive: the metadata document is fetched
+     * cross-origin by browser-based clients, and without a preflight answer the
+     * fetch fails before the document is read — which presents as "this connector
+     * cannot authorize" with nothing in any log to explain it.
+     */
+    OPTIONS: (request: Request) => Response;
+};
+export declare function createValMcpMetadata(oauth: ValOAuthConfig, scopesSupported: string[]): ValMcpMetadataHandlers;
+/**
+ * The `WWW-Authenticate` value for a refusal (RFC 6750 section 3, RFC 9728
+ * section 5.1).
+ *
+ * `resource_metadata` is the load-bearing parameter: it is how a client that has
+ * never seen this server learns where to authorize. A `401` without it is a dead
+ * end — the client knows it needs a token and has no way to find out from where.
+ */
+export declare function wwwAuthenticate(oauth: ValOAuthConfig, scopesSupported: string[], refusal?: {
+    error: string;
+    description: string;
+}): string;

package/dist/valbuild-mcp.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidmFsYnVpbGQtbWNwLmNqcy5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi9kZWNsYXJhdGlvbnMvc3JjL2luZGV4LmQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEifQ==