@valbuild/server 0.116.0 → 0.117.1

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# @valbuild/server
+
+## 0.117.1
+
+### Patch Changes
+
+- Updated dependencies [[`0ae7bac`](https://github.com/valbuild/val/commit/0ae7bac8a186460bc2b31f2ded89b00027bafb55)]:
+  - @valbuild/ui@0.117.1
+
+## 0.117.0
+
+### Minor Changes
+
+- [#582](https://github.com/valbuild/val/pull/582) [`fca3efa`](https://github.com/valbuild/val/commit/fca3efa389e2817401f55ea3dd184af7c611b807) Thanks [@freekh](https://github.com/freekh)! - Accept OAuth access tokens on the MCP endpoint, so editors can authorize as themselves
+
+  `initValMcp` takes an optional `oauth` config. Give it the authorization server's
+  URL and this endpoint's own URL, and every MCP call must then present an access
+  token that Val's authorization server issued:
+
+  ```ts
+  const { valMcpAuthorize, valMcpTools, valMcpMetadata } = initValMcp(
+    valModules,
+    config,
+    {
+      oauth: {
+        issuer: "https://admin.val.build",
+        resource: "https://your-app.com/api/mcp",
+      },
+    },
+  );
+  ```
+
+  The token is verified in your app — signature against the issuer's published
+  keys, plus issuer, audience and expiry — so the caller's identity is checked
+  rather than claimed. **Patches created over MCP now carry that profile as their
+  author**, which is what makes an edit made from a phone show up in the review
+  screen as somebody's rather than nobody's. Scopes are enforced too: a token
+  without `val:write` cannot reach a tool that writes.
+
+  Mount the discovery document so clients can find where to authorize:
+
+  ```ts
+  // app/.well-known/oauth-protected-resource/route.ts
+  import { valMcpMetadata } from "../../../val/mcp";
+  export const { GET, OPTIONS } = valMcpMetadata!;
+  ```
+
+  `valMcpMetadata` is `null` when no `oauth` config is given.
+
+  **Nothing changes if you leave `oauth` out.** Local development still works with
+  no authorization server, and an app already using a personal access token keeps
+  working as before.
+
+  One breaking change if you built your own host on `createValTools`:
+  `ValToolContext.auth` is now a tagged union, so `{ pat }` becomes
+  `{ type: "pat", pat }`. The new variant is
+  `{ type: "verified-profile", profileId, scopes }`, for a host that verified a
+  token itself.
+
+### Patch Changes
+
+- [#579](https://github.com/valbuild/val/pull/579) [`b2812ae`](https://github.com/valbuild/val/commit/b2812ae4ee03e005ecead3365f49c625e536f94d) Thanks [@freekh](https://github.com/freekh)! - Every release now ships a changelog. Each package's `CHANGELOG.md` records what
+  changed under the version that shipped it — with a link to the pull request, the
+  commit and the author — and the same entry becomes the body of the GitHub
+  Release for the tag. The file is included in the npm tarball, so it is also
+  readable from an installed copy.
+
+  Up to now those changelogs were generated empty, and the GitHub Releases with
+  them, so there was no record of what any given version contained. Releases from
+  this one on have one; earlier versions stay blank.
+
+- Updated dependencies [[`d94a40f`](https://github.com/valbuild/val/commit/d94a40f8bd11027636d183e293aced820b6f341f), [`b2812ae`](https://github.com/valbuild/val/commit/b2812ae4ee03e005ecead3365f49c625e536f94d)]:
+  - @valbuild/core@0.117.0
+  - @valbuild/shared@0.117.0
+  - @valbuild/ui@0.117.0

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

@@ -1,7 +1,8 @@
 export { createService, Service } from "./Service.js";
 export { createValApiRouter, createValServer, safeReadGit } from "./ValRouter.js";
 export { createValTools } from "./tools/index.js";
-export type { ValToolContext, ValToolDefinition, ValToolDefinitionJson, ValToolErrorCode, ValToolResult, ValTools, ValToolsOptions, } from "./tools/index.js";
+export { VAL_SCOPE_READ, VAL_SCOPE_WRITE, authorIdFromVerifiedSubject, } from "./tools/index.js";
+export type { ValScope, ValToolAuth, ValToolContext, ValToolDefinition, ValToolDefinitionJson, ValToolErrorCode, ValToolResult, ValTools, ValToolsOptions, } from "./tools/index.js";
 export { initHandlerOptions, createValOps } from "./valServerConfig.js";
 export { ValModuleLoader } from "./ValModuleLoader.js";
 export { getCompilerOptions } from "./getCompilerOptions.js";

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

@@ -1,6 +1,6 @@
 import type { ValModules } from "@valbuild/core";
 import type { ValServerConfig } from "../ValServer.js";
-import type { ValTools } from "./types.js";
+import { type ValTools } from "./types.js";
 export type ValToolsOptions = ValServerConfig;
 /**
  * Val's server-side tool registry.

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

@@ -1,2 +1,3 @@
 export { createValTools, type ValToolsOptions } from "./createValTools.js";
-export type { ValToolContext, ValToolDefinition, ValToolDefinitionJson, ValToolErrorCode, ValToolResult, ValTools, } from "./types.js";
+export { VAL_SCOPE_READ, VAL_SCOPE_WRITE, authorIdFromVerifiedSubject, } from "./types.js";
+export type { ValScope, ValToolAuth, ValToolContext, ValToolDefinition, ValToolDefinitionJson, ValToolErrorCode, ValToolResult, ValTools, } from "./types.js";

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

@@ -1,3 +1,4 @@
+import type { AuthorId } from "../ValOps.js";
 import type { Json } from "@valbuild/core";
 import type { z } from "zod";
 /**
@@ -74,14 +75,56 @@ export type ValToolDefinitionJson = Omit<ValToolDefinition, "inputSchema"> & {
     inputSchema: ReturnType<typeof z.toJSONSchema<z.ZodType>>;
 };
 /**
- * Who is calling, established once per request by the host.
+ * How the caller was established, and it is a union because there are two
+ * genuinely different answers — with different consequences downstream.
  *
- * There is deliberately no identity field here, only the credential. In proxy
- * mode the caller's own personal access token authenticates every downstream
- * call, so the backend decides who the caller is (`docs/plans/mcp.md` D.2). An
- * `authorId` alongside it would have to be filled in by the host, and the host
- * has no way to verify a PAT — so the field would be an unverified claim that
- * looks like a checked one, which is the confused-deputy shape D.6 rejects.
+ * The distinction that matters is **who checked**. A PAT is forwarded to the
+ * backend unchecked, because the app cannot resolve one; an access token is
+ * verified by the app itself, against a public key it does not hold and
+ * therefore cannot forge. The first is a credential being relayed. The second
+ * is a signature that has already been checked.
+ */
+export type ValToolAuth = {
+    type: "pat";
+    /**
+     * The caller's PAT. Never log this, never put it in a URL, and never let
+     * it reach a tool result.
+     *
+     * Relayed to the backend as-is: this app is not the authority on what the
+     * token may do, and the backend that is decides. Nothing is derived from
+     * it here — see `docs/plans/mcp.md` D.2.
+     */
+    pat: string;
+} | {
+    type: "verified-profile";
+    /**
+     * The profile the host **verified** — the `sub` of an access token whose
+     * signature, issuer, audience and expiry were all checked against the
+     * authorization server's published key.
+     *
+     * This field is the reason this type became a union, and an earlier
+     * version of this file argued no identity field should exist at all. That
+     * argument was about a specific case and stated too broadly: an id the
+     * host *asserts* on the strength of a credential it cannot check is an
+     * unverified claim dressed as a checked one, and that is still refused —
+     * it is why the `pat` variant carries no profile. An id the host
+     * *verified* cryptographically is a different thing, and it is the same
+     * standing the Studio has when it re-signs a session it established
+     * itself.
+     */
+    profileId: AuthorId;
+    /**
+     * The token's granted scopes, as the authorization server issued them.
+     *
+     * Enforced here as well as by the backend, deliberately. Two checks on
+     * one grant is not redundancy for its own sake: this one can refuse a
+     * write before it is attempted, so a token that may only read never
+     * reaches the code that builds a patch.
+     */
+    scopes: string[];
+};
+/**
+ * Who is calling, established once per request by the host.
  *
  * `null` means local fs mode, where there is no credential to hold and patches
  * are written with no author, exactly as the Studio does locally (D.1). In
@@ -90,16 +133,29 @@ export type ValToolDefinitionJson = Omit<ValToolDefinition, "inputSchema"> & {
  * would turn a missing credential into full access.
  */
 export type ValToolContext = {
-    auth: {
-        /**
-         * The caller's PAT. Never log this, never put it in a URL, and never let
-         * it reach a tool result.
-         */
-        pat: string;
-    } | null;
+    auth: ValToolAuth | null;
     /** Groups a run of related edits, when the host has such a notion. */
     sessionId: string | null;
 };
+/**
+ * Brand a verified subject as an {@link AuthorId}.
+ *
+ * `AuthorId` is a branded string so that an id cannot be conjured from any
+ * string that happens to be lying around — which is exactly the mistake this
+ * type is guarding against. That makes one assertion unavoidable at the boundary
+ * where a real id enters the system, so it lives here, once, with a name that
+ * says what makes it legitimate: the caller has *verified* this subject, not
+ * received it.
+ *
+ * Do not reach for this to satisfy a type. If you are holding a string you did
+ * not verify, the honest value is `null`.
+ */
+export declare function authorIdFromVerifiedSubject(subject: string): AuthorId;
+/** Read access. Every call needs it, the writes included. */
+export declare const VAL_SCOPE_READ = "val:read";
+/** Write access. Needed *in addition* by any tool not marked `readOnlyHint`. */
+export declare const VAL_SCOPE_WRITE = "val:write";
+export type ValScope = typeof VAL_SCOPE_READ | typeof VAL_SCOPE_WRITE;
 export type ValToolResult = {
     status: "ok";
     data: Json;

package/dist/valbuild-server.cjs.dev.js

@@ -11425,6 +11425,7 @@ function describeErrors(errors) {
  * failing clearly.
  */
 async function savePatch(deps, moduleFilePath, patch, onInvalid = "reject") {
+  var _ctx$auth;
   const {
     ops,
     ctx,
@@ -11460,13 +11461,24 @@ async function savePatch(deps, moduleFilePath, patch, onInvalid = "reject") {
     unresolved = speculative.errors;
   }
 
-  // Always null, and deliberately so. The app cannot resolve a PAT to a
-  // profile, so any id it put here would be an unverified claim dressed up as a
-  // checked one — and the request already carries the caller's own token, which
-  // is a better answer to "who did this" than anything the app could assert.
-  // Attributing the patch from that token is a backend concern; see
-  // `docs/plans/mcp.md` D.3.
-  const authorId = null;
+  /**
+   * Null on the PAT path, and the verified profile on the token path.
+   *
+   * The PAT case is unchanged and still deliberate: the app cannot resolve a
+   * PAT, so any id it wrote here would be an unverified claim dressed up as a
+   * checked one — and the request already carries the caller's own token, which
+   * is a better answer to "who did this" than anything the app could assert.
+   * Attributing that patch is the backend's job.
+   *
+   * The token case is the opposite situation, which is why it gets the opposite
+   * answer. The host verified a signature over a key it does not hold, so the
+   * profile is checked rather than claimed, and the backend has no token of its
+   * own to attribute from — the call reaches it under the app's API key. If this
+   * stayed null, every edit made through a signed-in editor's own session would
+   * land with no author at all, which is worse than useless on a CMS whose
+   * review screen is organised by who changed what.
+   */
+  const authorId = ((_ctx$auth = ctx.auth) === null || _ctx$auth === void 0 ? void 0 : _ctx$auth.type) === "verified-profile" ? ctx.auth.profileId : null;
   for (let attempt = 0; attempt < 2; attempt++) {
     const patchId = mintPatchId();
     // Re-derived on the retry rather than reused: reusing the ref that just
@@ -11690,6 +11702,80 @@ function rejectFileOps(patch) {
   };
 }
 
+/**
+ * The public surface of Val's server-side tool registry.
+ *
+ * Types only, deliberately: this file is the contract that the MCP hosts, the
+ * CLI's stdio transport and the tools themselves are all written against, and
+ * keeping it free of implementation means those can be built in any order
+ * without one of them owning the shape.
+ *
+ * The design this implements is `docs/plans/mcp.md`, Part A. Two constraints
+ * from it are load-bearing and easy to break by accident:
+ *
+ * 1. **Nothing here may import an MCP SDK.** That is what lets hosts other
+ *    than the template consume these tools, and it is not hypothetical
+ *    hygiene — the TypeScript SDK reorganised itself at v2.0.0, and a registry
+ *    coupled to it would have moved with it.
+ * 2. **The result type is deliberately not MCP's `CallToolResult`.** Each host
+ *    adapts {@link ValToolResult} at its own edge, which is also where an
+ *    error becomes an in-band `isError` result the model can recover from
+ *    rather than a transport failure.
+ */
+
+/** Why a tool call failed, in a form a host can map onto its own errors. */
+
+/**
+ * The same definition with `inputSchema` as JSON Schema, for hosts that want the
+ * wire shape rather than a Standard Schema.
+ *
+ * Typed as whatever zod's own converter produces, so deriving it needs no cast
+ * and no second hand-written description of the same input.
+ */
+
+/**
+ * How the caller was established, and it is a union because there are two
+ * genuinely different answers — with different consequences downstream.
+ *
+ * The distinction that matters is **who checked**. A PAT is forwarded to the
+ * backend unchecked, because the app cannot resolve one; an access token is
+ * verified by the app itself, against a public key it does not hold and
+ * therefore cannot forge. The first is a credential being relayed. The second
+ * is a signature that has already been checked.
+ */
+
+/**
+ * Who is calling, established once per request by the host.
+ *
+ * `null` means local fs mode, where there is no credential to hold and patches
+ * are written with no author, exactly as the Studio does locally (D.1). In
+ * proxy mode `null` is refused rather than falling back to the app's own API
+ * key: that key can do more than any single user, and quietly substituting it
+ * would turn a missing credential into full access.
+ */
+
+/**
+ * Brand a verified subject as an {@link AuthorId}.
+ *
+ * `AuthorId` is a branded string so that an id cannot be conjured from any
+ * string that happens to be lying around — which is exactly the mistake this
+ * type is guarding against. That makes one assertion unavoidable at the boundary
+ * where a real id enters the system, so it lives here, once, with a name that
+ * says what makes it legitimate: the caller has *verified* this subject, not
+ * received it.
+ *
+ * Do not reach for this to satisfy a type. If you are holding a string you did
+ * not verify, the honest value is `null`.
+ */
+function authorIdFromVerifiedSubject(subject) {
+  return subject;
+}
+
+/** Read access. Every call needs it, the writes included. */
+const VAL_SCOPE_READ = "val:read";
+/** Write access. Needed *in addition* by any tool not marked `readOnlyHint`. */
+const VAL_SCOPE_WRITE = "val:write";
+
 /**
  * How many callers' data layers to keep around in proxy mode.
  *
@@ -11756,6 +11842,10 @@ function createValTools(valModules, options) {
           message: describeZodError(parsed.error)
         };
       }
+      const insufficient = refuseInsufficientScope(tool, ctx);
+      if (insufficient) {
+        return insufficient;
+      }
       const resolved = resolveOps(ctx);
       if (resolved.status === "error") {
         return resolved.result;
@@ -11840,6 +11930,13 @@ function createOpsResolver(valModules, options) {
   // instance holds the token regardless — but it keeps credentials out of the
   // key set, which is the thing that ends up in a heap dump or an error dump.
   const byPatHash = new Map();
+  /**
+   * One instance for every verified caller, and unlike the PAT map that is
+   * correct rather than a shortcut: this instance authenticates with the app's
+   * own API key, so there is nothing per-caller in it to keep apart. Who did
+   * what travels as the patch's `authorId` instead — see `writePath`.
+   */
+  let sharedOps = null;
   return ctx => {
     if (!ctx.auth) {
       return {
@@ -11847,10 +11944,32 @@ function createOpsResolver(valModules, options) {
         result: {
           status: "error",
           code: "forbidden",
-          message: "This Val project talks to the Val content backend, so every call needs the caller's own personal access token. Run `val login` to get one."
+          message: "This Val project talks to the Val content backend, so every call needs a credential: an access token from the Val authorization server, or the caller's own personal access token from `val login`."
         }
       };
     }
+    if (ctx.auth.type === "verified-profile") {
+      if (!options.apiKey) {
+        // Proxy mode is inferred from the api key being present, so this is
+        // unreachable through `initHandlerOptions`. It stays because the
+        // alternative to refusing is building ops with no credential at all.
+        return {
+          status: "error",
+          result: {
+            status: "error",
+            code: "forbidden",
+            message: "This Val project has no API key configured, so a verified access token cannot be exchanged for backend access."
+          }
+        };
+      }
+      if (!sharedOps) {
+        sharedOps = createValOps(valModules, options);
+      }
+      return {
+        status: "ok",
+        ops: sharedOps
+      };
+    }
     const key = node_crypto.createHash("sha256").update(ctx.auth.pat).digest("hex");
     const cached = byPatHash.get(key);
     if (cached) {
@@ -11963,6 +12082,42 @@ function describeZodError(error) {
   }).join("; ");
 }
 
+/**
+ * Refuse a call the token was not granted, before anything is attempted.
+ *
+ * Derived from `readOnlyHint` rather than from a second list of tool names,
+ * because a second list is a thing that drifts. The derivation also fails in
+ * the safe direction: a tool that forgets the hint is treated as a write and
+ * demands the wider scope, rather than a write slipping through as a read.
+ *
+ * Only the verified-token path is checked. A PAT carries no scopes here by
+ * design — the backend resolves it and decides — so there is nothing to
+ * enforce, and inventing a default would be this app claiming an authority it
+ * does not have.
+ */
+function refuseInsufficientScope(tool, ctx) {
+  var _ctx$auth, _tool$annotations;
+  if (((_ctx$auth = ctx.auth) === null || _ctx$auth === void 0 ? void 0 : _ctx$auth.type) !== "verified-profile") {
+    return null;
+  }
+  // Read is needed by every call, including the writes: a tool that changes
+  // content reads it first, and `ValToolAuth` says as much. Checking only the
+  // wider scope would let a write-but-not-read token through here — today's
+  // verifier refuses such a token before this point, but `createValTools` is
+  // exported and another host may not.
+  const needed = (_tool$annotations = tool.annotations) !== null && _tool$annotations !== void 0 && _tool$annotations.readOnlyHint ? [VAL_SCOPE_READ] : [VAL_SCOPE_READ, VAL_SCOPE_WRITE];
+  const granted = ctx.auth.scopes;
+  const missing = needed.filter(scope => !granted.includes(scope));
+  if (missing.length === 0) {
+    return null;
+  }
+  return {
+    status: "error",
+    code: "forbidden",
+    message: `This access token does not have the ${missing.join(" and ")} scope, which ${tool.name} requires. Granted: ${granted.length > 0 ? granted.join(" ") : "(none)"}.`
+  };
+}
+
 const JsFileLookupMapping = [
 // NOTE: first one matching will be used
 [".cjs.d.ts", [".esm.js", ".mjs.js"]], [".cjs.js", [".esm.js", ".mjs.js"]], [".cjs", [".mjs"]], [".d.ts", [".js", ".esm.js", ".mjs.js"]]];
@@ -14150,6 +14305,8 @@ exports.DEFAULT_LOGIN_EXPIRES_IN_SECONDS = DEFAULT_LOGIN_EXPIRES_IN_SECONDS;
 exports.DEFAULT_LOGIN_HOST = DEFAULT_LOGIN_HOST;
 exports.DEFAULT_LOGIN_POLL_INTERVAL_SECONDS = DEFAULT_LOGIN_POLL_INTERVAL_SECONDS;
 exports.Service = Service;
+exports.VAL_SCOPE_READ = VAL_SCOPE_READ;
+exports.VAL_SCOPE_WRITE = VAL_SCOPE_WRITE;
 exports.ValFSHost = ValFSHost;
 exports.ValLoginError = ValLoginError;
 exports.ValModuleLoader = ValModuleLoader;
@@ -14157,6 +14314,7 @@ exports.ValOpsFS = ValOpsFS;
 exports.ValOpsHttp = ValOpsHttp;
 exports.ValSourceFileHandler = ValSourceFileHandler;
 exports.analyzeValModule = analyzeValModule;
+exports.authorIdFromVerifiedSubject = authorIdFromVerifiedSubject;
 exports.awaitValLoginConfirmation = awaitValLoginConfirmation;
 exports.checkRemoteRef = checkRemoteRef;
 exports.classifyJsonValuesOp = classifyJsonValuesOp;

package/dist/valbuild-server.cjs.prod.js

@@ -11425,6 +11425,7 @@ function describeErrors(errors) {
  * failing clearly.
  */
 async function savePatch(deps, moduleFilePath, patch, onInvalid = "reject") {
+  var _ctx$auth;
   const {
     ops,
     ctx,
@@ -11460,13 +11461,24 @@ async function savePatch(deps, moduleFilePath, patch, onInvalid = "reject") {
     unresolved = speculative.errors;
   }
 
-  // Always null, and deliberately so. The app cannot resolve a PAT to a
-  // profile, so any id it put here would be an unverified claim dressed up as a
-  // checked one — and the request already carries the caller's own token, which
-  // is a better answer to "who did this" than anything the app could assert.
-  // Attributing the patch from that token is a backend concern; see
-  // `docs/plans/mcp.md` D.3.
-  const authorId = null;
+  /**
+   * Null on the PAT path, and the verified profile on the token path.
+   *
+   * The PAT case is unchanged and still deliberate: the app cannot resolve a
+   * PAT, so any id it wrote here would be an unverified claim dressed up as a
+   * checked one — and the request already carries the caller's own token, which
+   * is a better answer to "who did this" than anything the app could assert.
+   * Attributing that patch is the backend's job.
+   *
+   * The token case is the opposite situation, which is why it gets the opposite
+   * answer. The host verified a signature over a key it does not hold, so the
+   * profile is checked rather than claimed, and the backend has no token of its
+   * own to attribute from — the call reaches it under the app's API key. If this
+   * stayed null, every edit made through a signed-in editor's own session would
+   * land with no author at all, which is worse than useless on a CMS whose
+   * review screen is organised by who changed what.
+   */
+  const authorId = ((_ctx$auth = ctx.auth) === null || _ctx$auth === void 0 ? void 0 : _ctx$auth.type) === "verified-profile" ? ctx.auth.profileId : null;
   for (let attempt = 0; attempt < 2; attempt++) {
     const patchId = mintPatchId();
     // Re-derived on the retry rather than reused: reusing the ref that just
@@ -11690,6 +11702,80 @@ function rejectFileOps(patch) {
   };
 }
 
+/**
+ * The public surface of Val's server-side tool registry.
+ *
+ * Types only, deliberately: this file is the contract that the MCP hosts, the
+ * CLI's stdio transport and the tools themselves are all written against, and
+ * keeping it free of implementation means those can be built in any order
+ * without one of them owning the shape.
+ *
+ * The design this implements is `docs/plans/mcp.md`, Part A. Two constraints
+ * from it are load-bearing and easy to break by accident:
+ *
+ * 1. **Nothing here may import an MCP SDK.** That is what lets hosts other
+ *    than the template consume these tools, and it is not hypothetical
+ *    hygiene — the TypeScript SDK reorganised itself at v2.0.0, and a registry
+ *    coupled to it would have moved with it.
+ * 2. **The result type is deliberately not MCP's `CallToolResult`.** Each host
+ *    adapts {@link ValToolResult} at its own edge, which is also where an
+ *    error becomes an in-band `isError` result the model can recover from
+ *    rather than a transport failure.
+ */
+
+/** Why a tool call failed, in a form a host can map onto its own errors. */
+
+/**
+ * The same definition with `inputSchema` as JSON Schema, for hosts that want the
+ * wire shape rather than a Standard Schema.
+ *
+ * Typed as whatever zod's own converter produces, so deriving it needs no cast
+ * and no second hand-written description of the same input.
+ */
+
+/**
+ * How the caller was established, and it is a union because there are two
+ * genuinely different answers — with different consequences downstream.
+ *
+ * The distinction that matters is **who checked**. A PAT is forwarded to the
+ * backend unchecked, because the app cannot resolve one; an access token is
+ * verified by the app itself, against a public key it does not hold and
+ * therefore cannot forge. The first is a credential being relayed. The second
+ * is a signature that has already been checked.
+ */
+
+/**
+ * Who is calling, established once per request by the host.
+ *
+ * `null` means local fs mode, where there is no credential to hold and patches
+ * are written with no author, exactly as the Studio does locally (D.1). In
+ * proxy mode `null` is refused rather than falling back to the app's own API
+ * key: that key can do more than any single user, and quietly substituting it
+ * would turn a missing credential into full access.
+ */
+
+/**
+ * Brand a verified subject as an {@link AuthorId}.
+ *
+ * `AuthorId` is a branded string so that an id cannot be conjured from any
+ * string that happens to be lying around — which is exactly the mistake this
+ * type is guarding against. That makes one assertion unavoidable at the boundary
+ * where a real id enters the system, so it lives here, once, with a name that
+ * says what makes it legitimate: the caller has *verified* this subject, not
+ * received it.
+ *
+ * Do not reach for this to satisfy a type. If you are holding a string you did
+ * not verify, the honest value is `null`.
+ */
+function authorIdFromVerifiedSubject(subject) {
+  return subject;
+}
+
+/** Read access. Every call needs it, the writes included. */
+const VAL_SCOPE_READ = "val:read";
+/** Write access. Needed *in addition* by any tool not marked `readOnlyHint`. */
+const VAL_SCOPE_WRITE = "val:write";
+
 /**
  * How many callers' data layers to keep around in proxy mode.
  *
@@ -11756,6 +11842,10 @@ function createValTools(valModules, options) {
           message: describeZodError(parsed.error)
         };
       }
+      const insufficient = refuseInsufficientScope(tool, ctx);
+      if (insufficient) {
+        return insufficient;
+      }
       const resolved = resolveOps(ctx);
       if (resolved.status === "error") {
         return resolved.result;
@@ -11840,6 +11930,13 @@ function createOpsResolver(valModules, options) {
   // instance holds the token regardless — but it keeps credentials out of the
   // key set, which is the thing that ends up in a heap dump or an error dump.
   const byPatHash = new Map();
+  /**
+   * One instance for every verified caller, and unlike the PAT map that is
+   * correct rather than a shortcut: this instance authenticates with the app's
+   * own API key, so there is nothing per-caller in it to keep apart. Who did
+   * what travels as the patch's `authorId` instead — see `writePath`.
+   */
+  let sharedOps = null;
   return ctx => {
     if (!ctx.auth) {
       return {
@@ -11847,10 +11944,32 @@ function createOpsResolver(valModules, options) {
         result: {
           status: "error",
           code: "forbidden",
-          message: "This Val project talks to the Val content backend, so every call needs the caller's own personal access token. Run `val login` to get one."
+          message: "This Val project talks to the Val content backend, so every call needs a credential: an access token from the Val authorization server, or the caller's own personal access token from `val login`."
         }
       };
     }
+    if (ctx.auth.type === "verified-profile") {
+      if (!options.apiKey) {
+        // Proxy mode is inferred from the api key being present, so this is
+        // unreachable through `initHandlerOptions`. It stays because the
+        // alternative to refusing is building ops with no credential at all.
+        return {
+          status: "error",
+          result: {
+            status: "error",
+            code: "forbidden",
+            message: "This Val project has no API key configured, so a verified access token cannot be exchanged for backend access."
+          }
+        };
+      }
+      if (!sharedOps) {
+        sharedOps = createValOps(valModules, options);
+      }
+      return {
+        status: "ok",
+        ops: sharedOps
+      };
+    }
     const key = node_crypto.createHash("sha256").update(ctx.auth.pat).digest("hex");
     const cached = byPatHash.get(key);
     if (cached) {
@@ -11963,6 +12082,42 @@ function describeZodError(error) {
   }).join("; ");
 }
 
+/**
+ * Refuse a call the token was not granted, before anything is attempted.
+ *
+ * Derived from `readOnlyHint` rather than from a second list of tool names,
+ * because a second list is a thing that drifts. The derivation also fails in
+ * the safe direction: a tool that forgets the hint is treated as a write and
+ * demands the wider scope, rather than a write slipping through as a read.
+ *
+ * Only the verified-token path is checked. A PAT carries no scopes here by
+ * design — the backend resolves it and decides — so there is nothing to
+ * enforce, and inventing a default would be this app claiming an authority it
+ * does not have.
+ */
+function refuseInsufficientScope(tool, ctx) {
+  var _ctx$auth, _tool$annotations;
+  if (((_ctx$auth = ctx.auth) === null || _ctx$auth === void 0 ? void 0 : _ctx$auth.type) !== "verified-profile") {
+    return null;
+  }
+  // Read is needed by every call, including the writes: a tool that changes
+  // content reads it first, and `ValToolAuth` says as much. Checking only the
+  // wider scope would let a write-but-not-read token through here — today's
+  // verifier refuses such a token before this point, but `createValTools` is
+  // exported and another host may not.
+  const needed = (_tool$annotations = tool.annotations) !== null && _tool$annotations !== void 0 && _tool$annotations.readOnlyHint ? [VAL_SCOPE_READ] : [VAL_SCOPE_READ, VAL_SCOPE_WRITE];
+  const granted = ctx.auth.scopes;
+  const missing = needed.filter(scope => !granted.includes(scope));
+  if (missing.length === 0) {
+    return null;
+  }
+  return {
+    status: "error",
+    code: "forbidden",
+    message: `This access token does not have the ${missing.join(" and ")} scope, which ${tool.name} requires. Granted: ${granted.length > 0 ? granted.join(" ") : "(none)"}.`
+  };
+}
+
 const JsFileLookupMapping = [
 // NOTE: first one matching will be used
 [".cjs.d.ts", [".esm.js", ".mjs.js"]], [".cjs.js", [".esm.js", ".mjs.js"]], [".cjs", [".mjs"]], [".d.ts", [".js", ".esm.js", ".mjs.js"]]];
@@ -14150,6 +14305,8 @@ exports.DEFAULT_LOGIN_EXPIRES_IN_SECONDS = DEFAULT_LOGIN_EXPIRES_IN_SECONDS;
 exports.DEFAULT_LOGIN_HOST = DEFAULT_LOGIN_HOST;
 exports.DEFAULT_LOGIN_POLL_INTERVAL_SECONDS = DEFAULT_LOGIN_POLL_INTERVAL_SECONDS;
 exports.Service = Service;
+exports.VAL_SCOPE_READ = VAL_SCOPE_READ;
+exports.VAL_SCOPE_WRITE = VAL_SCOPE_WRITE;
 exports.ValFSHost = ValFSHost;
 exports.ValLoginError = ValLoginError;
 exports.ValModuleLoader = ValModuleLoader;
@@ -14157,6 +14314,7 @@ exports.ValOpsFS = ValOpsFS;
 exports.ValOpsHttp = ValOpsHttp;
 exports.ValSourceFileHandler = ValSourceFileHandler;
 exports.analyzeValModule = analyzeValModule;
+exports.authorIdFromVerifiedSubject = authorIdFromVerifiedSubject;
 exports.awaitValLoginConfirmation = awaitValLoginConfirmation;
 exports.checkRemoteRef = checkRemoteRef;
 exports.classifyJsonValuesOp = classifyJsonValuesOp;

package/dist/valbuild-server.esm.js

@@ -11391,6 +11391,7 @@ function describeErrors(errors) {
  * failing clearly.
  */
 async function savePatch(deps, moduleFilePath, patch, onInvalid = "reject") {
+  var _ctx$auth;
   const {
     ops,
     ctx,
@@ -11426,13 +11427,24 @@ async function savePatch(deps, moduleFilePath, patch, onInvalid = "reject") {
     unresolved = speculative.errors;
   }
 
-  // Always null, and deliberately so. The app cannot resolve a PAT to a
-  // profile, so any id it put here would be an unverified claim dressed up as a
-  // checked one — and the request already carries the caller's own token, which
-  // is a better answer to "who did this" than anything the app could assert.
-  // Attributing the patch from that token is a backend concern; see
-  // `docs/plans/mcp.md` D.3.
-  const authorId = null;
+  /**
+   * Null on the PAT path, and the verified profile on the token path.
+   *
+   * The PAT case is unchanged and still deliberate: the app cannot resolve a
+   * PAT, so any id it wrote here would be an unverified claim dressed up as a
+   * checked one — and the request already carries the caller's own token, which
+   * is a better answer to "who did this" than anything the app could assert.
+   * Attributing that patch is the backend's job.
+   *
+   * The token case is the opposite situation, which is why it gets the opposite
+   * answer. The host verified a signature over a key it does not hold, so the
+   * profile is checked rather than claimed, and the backend has no token of its
+   * own to attribute from — the call reaches it under the app's API key. If this
+   * stayed null, every edit made through a signed-in editor's own session would
+   * land with no author at all, which is worse than useless on a CMS whose
+   * review screen is organised by who changed what.
+   */
+  const authorId = ((_ctx$auth = ctx.auth) === null || _ctx$auth === void 0 ? void 0 : _ctx$auth.type) === "verified-profile" ? ctx.auth.profileId : null;
   for (let attempt = 0; attempt < 2; attempt++) {
     const patchId = mintPatchId();
     // Re-derived on the retry rather than reused: reusing the ref that just
@@ -11656,6 +11668,80 @@ function rejectFileOps(patch) {
   };
 }
 
+/**
+ * The public surface of Val's server-side tool registry.
+ *
+ * Types only, deliberately: this file is the contract that the MCP hosts, the
+ * CLI's stdio transport and the tools themselves are all written against, and
+ * keeping it free of implementation means those can be built in any order
+ * without one of them owning the shape.
+ *
+ * The design this implements is `docs/plans/mcp.md`, Part A. Two constraints
+ * from it are load-bearing and easy to break by accident:
+ *
+ * 1. **Nothing here may import an MCP SDK.** That is what lets hosts other
+ *    than the template consume these tools, and it is not hypothetical
+ *    hygiene — the TypeScript SDK reorganised itself at v2.0.0, and a registry
+ *    coupled to it would have moved with it.
+ * 2. **The result type is deliberately not MCP's `CallToolResult`.** Each host
+ *    adapts {@link ValToolResult} at its own edge, which is also where an
+ *    error becomes an in-band `isError` result the model can recover from
+ *    rather than a transport failure.
+ */
+
+/** Why a tool call failed, in a form a host can map onto its own errors. */
+
+/**
+ * The same definition with `inputSchema` as JSON Schema, for hosts that want the
+ * wire shape rather than a Standard Schema.
+ *
+ * Typed as whatever zod's own converter produces, so deriving it needs no cast
+ * and no second hand-written description of the same input.
+ */
+
+/**
+ * How the caller was established, and it is a union because there are two
+ * genuinely different answers — with different consequences downstream.
+ *
+ * The distinction that matters is **who checked**. A PAT is forwarded to the
+ * backend unchecked, because the app cannot resolve one; an access token is
+ * verified by the app itself, against a public key it does not hold and
+ * therefore cannot forge. The first is a credential being relayed. The second
+ * is a signature that has already been checked.
+ */
+
+/**
+ * Who is calling, established once per request by the host.
+ *
+ * `null` means local fs mode, where there is no credential to hold and patches
+ * are written with no author, exactly as the Studio does locally (D.1). In
+ * proxy mode `null` is refused rather than falling back to the app's own API
+ * key: that key can do more than any single user, and quietly substituting it
+ * would turn a missing credential into full access.
+ */
+
+/**
+ * Brand a verified subject as an {@link AuthorId}.
+ *
+ * `AuthorId` is a branded string so that an id cannot be conjured from any
+ * string that happens to be lying around — which is exactly the mistake this
+ * type is guarding against. That makes one assertion unavoidable at the boundary
+ * where a real id enters the system, so it lives here, once, with a name that
+ * says what makes it legitimate: the caller has *verified* this subject, not
+ * received it.
+ *
+ * Do not reach for this to satisfy a type. If you are holding a string you did
+ * not verify, the honest value is `null`.
+ */
+function authorIdFromVerifiedSubject(subject) {
+  return subject;
+}
+
+/** Read access. Every call needs it, the writes included. */
+const VAL_SCOPE_READ = "val:read";
+/** Write access. Needed *in addition* by any tool not marked `readOnlyHint`. */
+const VAL_SCOPE_WRITE = "val:write";
+
 /**
  * How many callers' data layers to keep around in proxy mode.
  *
@@ -11722,6 +11808,10 @@ function createValTools(valModules, options) {
           message: describeZodError(parsed.error)
         };
       }
+      const insufficient = refuseInsufficientScope(tool, ctx);
+      if (insufficient) {
+        return insufficient;
+      }
       const resolved = resolveOps(ctx);
       if (resolved.status === "error") {
         return resolved.result;
@@ -11806,6 +11896,13 @@ function createOpsResolver(valModules, options) {
   // instance holds the token regardless — but it keeps credentials out of the
   // key set, which is the thing that ends up in a heap dump or an error dump.
   const byPatHash = new Map();
+  /**
+   * One instance for every verified caller, and unlike the PAT map that is
+   * correct rather than a shortcut: this instance authenticates with the app's
+   * own API key, so there is nothing per-caller in it to keep apart. Who did
+   * what travels as the patch's `authorId` instead — see `writePath`.
+   */
+  let sharedOps = null;
   return ctx => {
     if (!ctx.auth) {
       return {
@@ -11813,10 +11910,32 @@ function createOpsResolver(valModules, options) {
         result: {
           status: "error",
           code: "forbidden",
-          message: "This Val project talks to the Val content backend, so every call needs the caller's own personal access token. Run `val login` to get one."
+          message: "This Val project talks to the Val content backend, so every call needs a credential: an access token from the Val authorization server, or the caller's own personal access token from `val login`."
         }
       };
     }
+    if (ctx.auth.type === "verified-profile") {
+      if (!options.apiKey) {
+        // Proxy mode is inferred from the api key being present, so this is
+        // unreachable through `initHandlerOptions`. It stays because the
+        // alternative to refusing is building ops with no credential at all.
+        return {
+          status: "error",
+          result: {
+            status: "error",
+            code: "forbidden",
+            message: "This Val project has no API key configured, so a verified access token cannot be exchanged for backend access."
+          }
+        };
+      }
+      if (!sharedOps) {
+        sharedOps = createValOps(valModules, options);
+      }
+      return {
+        status: "ok",
+        ops: sharedOps
+      };
+    }
     const key = createHash("sha256").update(ctx.auth.pat).digest("hex");
     const cached = byPatHash.get(key);
     if (cached) {
@@ -11929,6 +12048,42 @@ function describeZodError(error) {
   }).join("; ");
 }
 
+/**
+ * Refuse a call the token was not granted, before anything is attempted.
+ *
+ * Derived from `readOnlyHint` rather than from a second list of tool names,
+ * because a second list is a thing that drifts. The derivation also fails in
+ * the safe direction: a tool that forgets the hint is treated as a write and
+ * demands the wider scope, rather than a write slipping through as a read.
+ *
+ * Only the verified-token path is checked. A PAT carries no scopes here by
+ * design — the backend resolves it and decides — so there is nothing to
+ * enforce, and inventing a default would be this app claiming an authority it
+ * does not have.
+ */
+function refuseInsufficientScope(tool, ctx) {
+  var _ctx$auth, _tool$annotations;
+  if (((_ctx$auth = ctx.auth) === null || _ctx$auth === void 0 ? void 0 : _ctx$auth.type) !== "verified-profile") {
+    return null;
+  }
+  // Read is needed by every call, including the writes: a tool that changes
+  // content reads it first, and `ValToolAuth` says as much. Checking only the
+  // wider scope would let a write-but-not-read token through here — today's
+  // verifier refuses such a token before this point, but `createValTools` is
+  // exported and another host may not.
+  const needed = (_tool$annotations = tool.annotations) !== null && _tool$annotations !== void 0 && _tool$annotations.readOnlyHint ? [VAL_SCOPE_READ] : [VAL_SCOPE_READ, VAL_SCOPE_WRITE];
+  const granted = ctx.auth.scopes;
+  const missing = needed.filter(scope => !granted.includes(scope));
+  if (missing.length === 0) {
+    return null;
+  }
+  return {
+    status: "error",
+    code: "forbidden",
+    message: `This access token does not have the ${missing.join(" and ")} scope, which ${tool.name} requires. Granted: ${granted.length > 0 ? granted.join(" ") : "(none)"}.`
+  };
+}
+
 const JsFileLookupMapping = [
 // NOTE: first one matching will be used
 [".cjs.d.ts", [".esm.js", ".mjs.js"]], [".cjs.js", [".esm.js", ".mjs.js"]], [".cjs", [".mjs"]], [".d.ts", [".js", ".esm.js", ".mjs.js"]]];
@@ -14108,4 +14263,4 @@ function readCapturedReport(snapshotDir) {
   return JSON.parse(fs.readFileSync(reportPath, "utf-8"));
 }
 
-export { DEFAULT_LOGIN_EXPIRES_IN_SECONDS, DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_POLL_INTERVAL_SECONDS, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, classifyJsonValuesOp, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValModuleFileInspector, createValOps, createValServer, createValTools, currentFixHandlers, decodeJwtWithoutVerifying, describePatchStoreProblems, downloadFileFromRemote, encodeJwt, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, findAndEvalValConfigFile, findJsonEntryFilePath, fixHandlers, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, handleCheckAllFiles, handleFileMetadata, handleJsonValuesExtractEntry, handleRemoteFileCheck, handleRemoteFileDownload, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleUniqueFolderCheck, initHandlerOptions, loadValModules, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, readCapturedReport, readPatchStore, rebaseContentOp, replaySnapshot, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata, verifyJwt };
+export { DEFAULT_LOGIN_EXPIRES_IN_SECONDS, DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_POLL_INTERVAL_SECONDS, Service, VAL_SCOPE_READ, VAL_SCOPE_WRITE, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, authorIdFromVerifiedSubject, awaitValLoginConfirmation, checkRemoteRef, classifyJsonValuesOp, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValModuleFileInspector, createValOps, createValServer, createValTools, currentFixHandlers, decodeJwtWithoutVerifying, describePatchStoreProblems, downloadFileFromRemote, encodeJwt, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, findAndEvalValConfigFile, findJsonEntryFilePath, fixHandlers, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, handleCheckAllFiles, handleFileMetadata, handleJsonValuesExtractEntry, handleRemoteFileCheck, handleRemoteFileDownload, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleUniqueFolderCheck, initHandlerOptions, loadValModules, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, readCapturedReport, readPatchStore, rebaseContentOp, replaySnapshot, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata, verifyJwt };

package/package.json

@@ -16,7 +16,7 @@
     "./package.json": "./package.json"
   },
   "types": "dist/valbuild-server.cjs.d.ts",
-  "version": "0.116.0",
+  "version": "0.117.1",
   "devDependencies": {
     "@prettier/sync": "^0.6.1",
     "@types/jest": "^30.0.0"
@@ -29,14 +29,15 @@
     "typescript": "^6.0.3",
     "zod": "^4.4.3",
     "zod-validation-error": "^5.0.0",
-    "@valbuild/core": "0.111.0",
-    "@valbuild/shared": "0.116.0",
-    "@valbuild/ui": "0.116.0"
+    "@valbuild/core": "0.117.0",
+    "@valbuild/shared": "0.117.0",
+    "@valbuild/ui": "0.117.1"
   },
   "engines": {
     "node": "^20.19.0 || >=22"
   },
   "files": [
+    "CHANGELOG.md",
     "dist"
   ],
   "scripts": {