@valbuild/server 0.111.0 → 0.113.0

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

@@ -5,4 +5,4 @@ import { ValidationError } from "@valbuild/core";
  * There is no schema in hand here — a `ValidationError` carries only the value
  * it flagged — so the shape is all there is to go on.
  */
-export declare function getValidationErrorFileRef(validationError: ValidationError): any;
+export declare function getValidationErrorFileRef(validationError: ValidationError): string | null;

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

@@ -1,9 +1,54 @@
-export type JwtPayload = {
-    sub: string;
-    exp: number;
-    org: string;
-    project: string;
+import { z } from "zod";
+declare const JwtPayloadSchema: z.ZodObject<{
+    sub: z.ZodString;
+    exp: z.ZodNumber;
+    org: z.ZodString;
+    project: z.ZodString;
+}, z.core.$loose>;
+export type JwtPayload = z.infer<typeof JwtPayloadSchema>;
+export type JwtFailureReason = 
+/** Not a JWT we issued: wrong number of segments, bad header, or a payload that is not a Val payload. */
+"malformed"
+/** The HMAC did not match: the token was forged or tampered with. */
+ | "invalid-signature"
+/** The token parsed and verified, but `exp` is in the past. */
+ | "expired"
+/** Programming error: {@link verifyJwt} was called without a secret. */
+ | "missing-secret";
+export type JwtFailure = {
+    success: false;
+    reason: JwtFailureReason;
+    message: string;
 };
-export declare function decodeJwt(token: string, secretKey?: string): JwtPayload | null;
+export type JwtResult = {
+    success: true;
+    data: JwtPayload;
+} | JwtFailure;
+/**
+ * Verify a JWT that we issued with {@link encodeJwt}, and return its payload.
+ *
+ * Checks, in order: the segment count, the header (`alg` is pinned to HS256, so
+ * algorithm confusion is rejected before the signature is looked at), the HMAC
+ * (compared in constant time), the payload shape, and `exp`.
+ *
+ * There is deliberately no way to make this skip the signature check: the
+ * secret is required, and an empty one is a failure rather than a token that
+ * validates against `HMAC("")`. Use {@link decodeJwtWithoutVerifying} - and read
+ * what it says - when you genuinely do not hold the signing key.
+ */
+export declare function verifyJwt(token: string, secretKey: string): JwtResult;
+/**
+ * Parse a JWT's payload **without checking its signature**.
+ *
+ * The header, the payload shape and `exp` are still validated, but nothing here
+ * establishes that the token was issued by anyone in particular. Only use this
+ * for a token whose authenticity is already established by the channel it
+ * arrived on - the app token we fetch from val.build over an api-key
+ * authenticated HTTPS request is the one such case. Anything that arrives from
+ * a browser (a cookie, a header, a query parameter) must go through
+ * {@link verifyJwt}.
+ */
+export declare function decodeJwtWithoutVerifying(token: string): JwtResult;
 export declare function getExpire(): number;
 export declare function encodeJwt(payload: object, sessionKey: string): string;
+export {};

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

@@ -1,4 +1,4 @@
-import { PatchId } from "@valbuild/core";
+import { ModuleFilePath, PatchId } from "@valbuild/core";
 import { z } from "zod";
 import type { AuthorId, BaseSha } from "./ValOps.js";
 import { PatchLogEntry, PatchLogProblem } from "./patchLog.js";
@@ -32,14 +32,14 @@ export declare const FSPatch: z.ZodObject<{
     patch: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         op: z.ZodLiteral<"add">;
         path: z.ZodArray<z.ZodString>;
-        value: z.ZodType<JSONValueT, unknown, z.core.$ZodTypeInternals<JSONValueT, unknown>>;
+        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"remove">;
         path: z.ZodTuple<[z.ZodString], z.ZodString>;
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"replace">;
         path: z.ZodArray<z.ZodString>;
-        value: z.ZodType<JSONValueT, unknown, z.core.$ZodTypeInternals<JSONValueT, unknown>>;
+        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"move">;
         from: z.ZodTuple<[z.ZodString], z.ZodString>;
@@ -51,15 +51,15 @@ export declare const FSPatch: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"test">;
         path: z.ZodArray<z.ZodString>;
-        value: z.ZodType<JSONValueT, unknown, z.core.$ZodTypeInternals<JSONValueT, unknown>>;
+        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"file">;
         path: z.ZodArray<z.ZodString>;
         filePath: z.ZodString;
-        value: z.ZodType<JSONValueT, unknown, z.core.$ZodTypeInternals<JSONValueT, unknown>>;
+        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
         remote: z.ZodBoolean;
         nestedFilePath: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        metadata: z.ZodOptional<z.ZodType<JSONValueT, unknown, z.core.$ZodTypeInternals<JSONValueT, unknown>>>;
+        metadata: z.ZodOptional<z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>>;
     }, z.core.$strict>], "op">>;
     patchId: z.ZodString;
     baseSha: z.ZodString & z.ZodType<BaseSha, string, z.core.$ZodTypeInternals<BaseSha, string>>;

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

@@ -1936,45 +1936,142 @@ class Service {
   }
 }
 
-function decodeJwt(token, secretKey) {
+const JwtPayloadSchema = z.z.object({
+  sub: z.z.string(),
+  exp: z.z.number(),
+  org: z.z.string(),
+  project: z.z.string()
+})
+// NOTE: passthrough, because the session cookie payload carries more than
+// this (the val.build token, notably). This is the minimum every Val JWT has.
+.passthrough();
+/**
+ * `exp` is an absolute Unix timestamp: a token is rejected once that moment has
+ * passed, with this much slack to absorb clock drift between whoever signed the
+ * token and us.
+ */
+const CLOCK_SKEW_LEEWAY_SECONDS = 60;
+function failure(reason, message) {
+  // NOTE: deliberately never logs the token itself - it is a credential, and
+  // anything we print here ends up in the host's request logs.
+  console.debug(`Invalid JWT (${reason}): ${message}`);
+  return {
+    success: false,
+    reason,
+    message
+  };
+}
+function splitToken(token) {
   const [headerBase64, payloadBase64, signatureBase64, ...rest] = token.split(".");
   if (!headerBase64 || !payloadBase64 || !signatureBase64 || rest.length > 0) {
-    console.debug("Invalid JWT: format is not exactly {header}.{payload}.{signature}", token);
     return null;
   }
+  return {
+    headerBase64,
+    payloadBase64,
+    signatureBase64
+  };
+}
+
+/** Returns the failure if the header is not one of ours, or null if it is fine. */
+function verifyHeader(headerBase64) {
+  let parsedHeader;
   try {
-    const parsedHeader = JSON.parse(Buffer.from(headerBase64, "base64").toString("utf8"));
-    const headerVerification = JwtHeaderSchema.safeParse(parsedHeader);
-    if (!headerVerification.success) {
-      console.debug("Invalid JWT: invalid header", parsedHeader);
-      return null;
-    }
-    if (headerVerification.data.typ !== jwtHeader.typ) {
-      console.debug("Invalid JWT: invalid header typ", parsedHeader);
-      return null;
-    }
-    if (headerVerification.data.alg !== jwtHeader.alg) {
-      console.debug("Invalid JWT: invalid header alg", parsedHeader);
-      return null;
-    }
-  } catch (err) {
-    console.debug("Invalid JWT: could not parse header", err);
-    return null;
+    parsedHeader = JSON.parse(Buffer.from(headerBase64, "base64").toString("utf8"));
+  } catch {
+    return failure("malformed", "could not parse header");
   }
-  if (secretKey) {
-    const signature = crypto__default["default"].createHmac("sha256", secretKey).update(`${headerBase64}.${payloadBase64}`).digest("base64");
-    if (signature !== signatureBase64) {
-      console.debug("Invalid JWT: invalid signature");
-      return null;
-    }
+  const headerVerification = JwtHeaderSchema.safeParse(parsedHeader);
+  if (!headerVerification.success) {
+    // NOTE: JwtHeaderSchema pins alg to HS256, so `alg: "none"` and every other
+    // algorithm-confusion header is rejected here, before we look at the
+    // signature at all.
+    return failure("malformed", "unsupported header");
   }
+  return null;
+}
+function parsePayload(payloadBase64) {
+  let parsedPayload;
   try {
-    const parsedPayload = JSON.parse(Buffer.from(payloadBase64, "base64").toString("utf8"));
-    return parsedPayload;
-  } catch (err) {
-    console.debug("Invalid JWT: could not parse payload", err);
-    return null;
+    parsedPayload = JSON.parse(Buffer.from(payloadBase64, "base64").toString("utf8"));
+  } catch {
+    return failure("malformed", "could not parse payload");
   }
+  const payloadVerification = JwtPayloadSchema.safeParse(parsedPayload);
+  if (!payloadVerification.success) {
+    return failure("malformed", "payload is not a Val JWT payload");
+  }
+  const payload = payloadVerification.data;
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  if (payload.exp + CLOCK_SKEW_LEEWAY_SECONDS <= nowSeconds) {
+    return failure("expired", "token expired");
+  }
+  return {
+    success: true,
+    data: payload
+  };
+}
+
+/**
+ * Verify a JWT that we issued with {@link encodeJwt}, and return its payload.
+ *
+ * Checks, in order: the segment count, the header (`alg` is pinned to HS256, so
+ * algorithm confusion is rejected before the signature is looked at), the HMAC
+ * (compared in constant time), the payload shape, and `exp`.
+ *
+ * There is deliberately no way to make this skip the signature check: the
+ * secret is required, and an empty one is a failure rather than a token that
+ * validates against `HMAC("")`. Use {@link decodeJwtWithoutVerifying} - and read
+ * what it says - when you genuinely do not hold the signing key.
+ */
+function verifyJwt(token, secretKey) {
+  if (!secretKey) {
+    return failure("missing-secret", "no secret key was provided");
+  }
+  const segments = splitToken(token);
+  if (!segments) {
+    return failure("malformed", "format is not exactly {header}.{payload}.{signature}");
+  }
+  const {
+    headerBase64,
+    payloadBase64,
+    signatureBase64
+  } = segments;
+  const headerFailure = verifyHeader(headerBase64);
+  if (headerFailure) {
+    return headerFailure;
+  }
+  const expectedSignature = crypto__default["default"].createHmac("sha256", secretKey).update(`${headerBase64}.${payloadBase64}`).digest();
+  const actualSignature = Buffer.from(signatureBase64, "base64");
+  // NOTE: the length check is what makes timingSafeEqual usable at all (it
+  // throws on a length mismatch), and the length of an HMAC-SHA256 is public.
+  if (actualSignature.length !== expectedSignature.length || !crypto__default["default"].timingSafeEqual(actualSignature, expectedSignature)) {
+    return failure("invalid-signature", "signature does not match");
+  }
+  return parsePayload(payloadBase64);
+}
+
+/**
+ * Parse a JWT's payload **without checking its signature**.
+ *
+ * The header, the payload shape and `exp` are still validated, but nothing here
+ * establishes that the token was issued by anyone in particular. Only use this
+ * for a token whose authenticity is already established by the channel it
+ * arrived on - the app token we fetch from val.build over an api-key
+ * authenticated HTTPS request is the one such case. Anything that arrives from
+ * a browser (a cookie, a header, a query parameter) must go through
+ * {@link verifyJwt}.
+ */
+function decodeJwtWithoutVerifying(token) {
+  const segments = splitToken(token);
+  if (!segments) {
+    return failure("malformed", "format is not exactly {header}.{payload}.{signature}");
+  }
+  const headerFailure = verifyHeader(segments.headerBase64);
+  if (headerFailure) {
+    return headerFailure;
+  }
+  return parsePayload(segments.payloadBase64);
 }
 function getExpire() {
   return Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 4; // 4 days
@@ -7618,7 +7715,20 @@ const ValServer = (valModules, options, callbacks) => {
     }).then(async res => {
       if (res.status === 200) {
         const token = await res.text();
-        const verification = ValAppJwtPayload.safeParse(decodeJwt(token));
+        // NOTE: this token is signed by val.build with a key we do not
+        // hold, so we cannot verify it. What stands in for a signature check
+        // is where it came from: the POST above, authenticated with the
+        // project's api key, to the configured `valBuildUrl`. It is not user
+        // input - but it is only as trustworthy as that host and that
+        // channel, and `valBuildUrl` is overridable (`opts.valBuildUrl`,
+        // `VAL_BUILD_URL`) and not required to be https. Point it at a plain
+        // http host and this payload - which is re-signed into the session
+        // cookie below - is whatever the network says it is.
+        const decoded = decodeJwtWithoutVerifying(token);
+        if (!decoded.success) {
+          return null;
+        }
+        const verification = ValAppJwtPayload.safeParse(decoded.data);
         if (!verification.success) {
           return null;
         }
@@ -7650,8 +7760,8 @@ const ValServer = (valModules, options, callbacks) => {
       }
     }
     if (typeof cookie === "string") {
-      const decodedToken = decodeJwt(cookie, options.valSecret);
-      if (!decodedToken) {
+      const verifiedToken = verifyJwt(cookie, options.valSecret);
+      if (!verifiedToken.success) {
         if (serverOps instanceof ValOpsFS) {
           return {
             error: null,
@@ -7659,10 +7769,10 @@ const ValServer = (valModules, options, callbacks) => {
           };
         }
         return {
-          error: "Could not verify session (invalid token). You will need to login again."
+          error: sessionErrorMessage(verifiedToken.reason)
         };
       }
-      const verification = IntegratedServerJwtPayload.safeParse(decodedToken);
+      const verification = IntegratedServerJwtPayload.safeParse(verifiedToken.data);
       if (!verification.success) {
         if (serverOps instanceof ValOpsFS) {
           return {
@@ -7671,7 +7781,7 @@ const ValServer = (valModules, options, callbacks) => {
           };
         }
         return {
-          error: "Session invalid or, most likely, expired. You will need to login again."
+          error: "Session invalid. You will need to login again."
         };
       }
       return {
@@ -10151,25 +10261,41 @@ const IntegratedServerJwtPayload = z.z.object({
   org: z.z.string(),
   project: z.z.string()
 });
+/**
+ * The message we show the user when their session cookie does not verify. The
+ * distinction matters: an expired session is normal and self-explanatory, while
+ * a bad signature means the cookie was tampered with or `VAL_SECRET` changed.
+ */
+function sessionErrorMessage(reason) {
+  switch (reason) {
+    case "expired":
+      return "Session expired. You will need to login again.";
+    case "malformed":
+    case "invalid-signature":
+      return "Could not verify session (invalid token). You will need to login again.";
+    case "missing-secret":
+      return "Setup is not correct: secret is missing";
+  }
+}
 async function withAuth(secret, cookies, errorMessageType, handler) {
   const cookie = cookies[internal.VAL_SESSION_COOKIE];
   if (typeof cookie === "string") {
-    const decodedToken = decodeJwt(cookie, secret);
-    if (!decodedToken) {
+    const verifiedToken = verifyJwt(cookie, secret);
+    if (!verifiedToken.success) {
       return {
         status: 401,
         json: {
-          message: "Could not verify session. You will need to login again.",
-          details: "Invalid token"
+          message: sessionErrorMessage(verifiedToken.reason),
+          details: verifiedToken.reason
         }
       };
     }
-    const verification = IntegratedServerJwtPayload.safeParse(decodedToken);
+    const verification = IntegratedServerJwtPayload.safeParse(verifiedToken.data);
     if (!verification.success) {
       return {
         status: 401,
         json: {
-          message: "Session invalid or, most likely, expired. You will need to login again.",
+          message: "Session invalid. You will need to login again.",
           details: zodValidationError.fromError(verification.error).toString()
         }
       };
@@ -12862,7 +12988,7 @@ exports.createValApiRouter = createValApiRouter;
 exports.createValModuleFileInspector = createValModuleFileInspector;
 exports.createValServer = createValServer;
 exports.currentFixHandlers = currentFixHandlers;
-exports.decodeJwt = decodeJwt;
+exports.decodeJwtWithoutVerifying = decodeJwtWithoutVerifying;
 exports.describePatchStoreProblems = describePatchStoreProblems;
 exports.downloadFileFromRemote = downloadFileFromRemote;
 exports.encodeJwt = encodeJwt;
@@ -12904,3 +13030,4 @@ exports.safeReadGit = safeReadGit;
 exports.startValLogin = startValLogin;
 exports.uploadRemoteFile = uploadRemoteFile;
 exports.validateMetadata = validateMetadata;
+exports.verifyJwt = verifyJwt;

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

@@ -1936,45 +1936,142 @@ class Service {
   }
 }
 
-function decodeJwt(token, secretKey) {
+const JwtPayloadSchema = z.z.object({
+  sub: z.z.string(),
+  exp: z.z.number(),
+  org: z.z.string(),
+  project: z.z.string()
+})
+// NOTE: passthrough, because the session cookie payload carries more than
+// this (the val.build token, notably). This is the minimum every Val JWT has.
+.passthrough();
+/**
+ * `exp` is an absolute Unix timestamp: a token is rejected once that moment has
+ * passed, with this much slack to absorb clock drift between whoever signed the
+ * token and us.
+ */
+const CLOCK_SKEW_LEEWAY_SECONDS = 60;
+function failure(reason, message) {
+  // NOTE: deliberately never logs the token itself - it is a credential, and
+  // anything we print here ends up in the host's request logs.
+  console.debug(`Invalid JWT (${reason}): ${message}`);
+  return {
+    success: false,
+    reason,
+    message
+  };
+}
+function splitToken(token) {
   const [headerBase64, payloadBase64, signatureBase64, ...rest] = token.split(".");
   if (!headerBase64 || !payloadBase64 || !signatureBase64 || rest.length > 0) {
-    console.debug("Invalid JWT: format is not exactly {header}.{payload}.{signature}", token);
     return null;
   }
+  return {
+    headerBase64,
+    payloadBase64,
+    signatureBase64
+  };
+}
+
+/** Returns the failure if the header is not one of ours, or null if it is fine. */
+function verifyHeader(headerBase64) {
+  let parsedHeader;
   try {
-    const parsedHeader = JSON.parse(Buffer.from(headerBase64, "base64").toString("utf8"));
-    const headerVerification = JwtHeaderSchema.safeParse(parsedHeader);
-    if (!headerVerification.success) {
-      console.debug("Invalid JWT: invalid header", parsedHeader);
-      return null;
-    }
-    if (headerVerification.data.typ !== jwtHeader.typ) {
-      console.debug("Invalid JWT: invalid header typ", parsedHeader);
-      return null;
-    }
-    if (headerVerification.data.alg !== jwtHeader.alg) {
-      console.debug("Invalid JWT: invalid header alg", parsedHeader);
-      return null;
-    }
-  } catch (err) {
-    console.debug("Invalid JWT: could not parse header", err);
-    return null;
+    parsedHeader = JSON.parse(Buffer.from(headerBase64, "base64").toString("utf8"));
+  } catch {
+    return failure("malformed", "could not parse header");
   }
-  if (secretKey) {
-    const signature = crypto__default["default"].createHmac("sha256", secretKey).update(`${headerBase64}.${payloadBase64}`).digest("base64");
-    if (signature !== signatureBase64) {
-      console.debug("Invalid JWT: invalid signature");
-      return null;
-    }
+  const headerVerification = JwtHeaderSchema.safeParse(parsedHeader);
+  if (!headerVerification.success) {
+    // NOTE: JwtHeaderSchema pins alg to HS256, so `alg: "none"` and every other
+    // algorithm-confusion header is rejected here, before we look at the
+    // signature at all.
+    return failure("malformed", "unsupported header");
   }
+  return null;
+}
+function parsePayload(payloadBase64) {
+  let parsedPayload;
   try {
-    const parsedPayload = JSON.parse(Buffer.from(payloadBase64, "base64").toString("utf8"));
-    return parsedPayload;
-  } catch (err) {
-    console.debug("Invalid JWT: could not parse payload", err);
-    return null;
+    parsedPayload = JSON.parse(Buffer.from(payloadBase64, "base64").toString("utf8"));
+  } catch {
+    return failure("malformed", "could not parse payload");
   }
+  const payloadVerification = JwtPayloadSchema.safeParse(parsedPayload);
+  if (!payloadVerification.success) {
+    return failure("malformed", "payload is not a Val JWT payload");
+  }
+  const payload = payloadVerification.data;
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  if (payload.exp + CLOCK_SKEW_LEEWAY_SECONDS <= nowSeconds) {
+    return failure("expired", "token expired");
+  }
+  return {
+    success: true,
+    data: payload
+  };
+}
+
+/**
+ * Verify a JWT that we issued with {@link encodeJwt}, and return its payload.
+ *
+ * Checks, in order: the segment count, the header (`alg` is pinned to HS256, so
+ * algorithm confusion is rejected before the signature is looked at), the HMAC
+ * (compared in constant time), the payload shape, and `exp`.
+ *
+ * There is deliberately no way to make this skip the signature check: the
+ * secret is required, and an empty one is a failure rather than a token that
+ * validates against `HMAC("")`. Use {@link decodeJwtWithoutVerifying} - and read
+ * what it says - when you genuinely do not hold the signing key.
+ */
+function verifyJwt(token, secretKey) {
+  if (!secretKey) {
+    return failure("missing-secret", "no secret key was provided");
+  }
+  const segments = splitToken(token);
+  if (!segments) {
+    return failure("malformed", "format is not exactly {header}.{payload}.{signature}");
+  }
+  const {
+    headerBase64,
+    payloadBase64,
+    signatureBase64
+  } = segments;
+  const headerFailure = verifyHeader(headerBase64);
+  if (headerFailure) {
+    return headerFailure;
+  }
+  const expectedSignature = crypto__default["default"].createHmac("sha256", secretKey).update(`${headerBase64}.${payloadBase64}`).digest();
+  const actualSignature = Buffer.from(signatureBase64, "base64");
+  // NOTE: the length check is what makes timingSafeEqual usable at all (it
+  // throws on a length mismatch), and the length of an HMAC-SHA256 is public.
+  if (actualSignature.length !== expectedSignature.length || !crypto__default["default"].timingSafeEqual(actualSignature, expectedSignature)) {
+    return failure("invalid-signature", "signature does not match");
+  }
+  return parsePayload(payloadBase64);
+}
+
+/**
+ * Parse a JWT's payload **without checking its signature**.
+ *
+ * The header, the payload shape and `exp` are still validated, but nothing here
+ * establishes that the token was issued by anyone in particular. Only use this
+ * for a token whose authenticity is already established by the channel it
+ * arrived on - the app token we fetch from val.build over an api-key
+ * authenticated HTTPS request is the one such case. Anything that arrives from
+ * a browser (a cookie, a header, a query parameter) must go through
+ * {@link verifyJwt}.
+ */
+function decodeJwtWithoutVerifying(token) {
+  const segments = splitToken(token);
+  if (!segments) {
+    return failure("malformed", "format is not exactly {header}.{payload}.{signature}");
+  }
+  const headerFailure = verifyHeader(segments.headerBase64);
+  if (headerFailure) {
+    return headerFailure;
+  }
+  return parsePayload(segments.payloadBase64);
 }
 function getExpire() {
   return Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 4; // 4 days
@@ -7618,7 +7715,20 @@ const ValServer = (valModules, options, callbacks) => {
     }).then(async res => {
       if (res.status === 200) {
         const token = await res.text();
-        const verification = ValAppJwtPayload.safeParse(decodeJwt(token));
+        // NOTE: this token is signed by val.build with a key we do not
+        // hold, so we cannot verify it. What stands in for a signature check
+        // is where it came from: the POST above, authenticated with the
+        // project's api key, to the configured `valBuildUrl`. It is not user
+        // input - but it is only as trustworthy as that host and that
+        // channel, and `valBuildUrl` is overridable (`opts.valBuildUrl`,
+        // `VAL_BUILD_URL`) and not required to be https. Point it at a plain
+        // http host and this payload - which is re-signed into the session
+        // cookie below - is whatever the network says it is.
+        const decoded = decodeJwtWithoutVerifying(token);
+        if (!decoded.success) {
+          return null;
+        }
+        const verification = ValAppJwtPayload.safeParse(decoded.data);
         if (!verification.success) {
           return null;
         }
@@ -7650,8 +7760,8 @@ const ValServer = (valModules, options, callbacks) => {
       }
     }
     if (typeof cookie === "string") {
-      const decodedToken = decodeJwt(cookie, options.valSecret);
-      if (!decodedToken) {
+      const verifiedToken = verifyJwt(cookie, options.valSecret);
+      if (!verifiedToken.success) {
         if (serverOps instanceof ValOpsFS) {
           return {
             error: null,
@@ -7659,10 +7769,10 @@ const ValServer = (valModules, options, callbacks) => {
           };
         }
         return {
-          error: "Could not verify session (invalid token). You will need to login again."
+          error: sessionErrorMessage(verifiedToken.reason)
         };
       }
-      const verification = IntegratedServerJwtPayload.safeParse(decodedToken);
+      const verification = IntegratedServerJwtPayload.safeParse(verifiedToken.data);
       if (!verification.success) {
         if (serverOps instanceof ValOpsFS) {
           return {
@@ -7671,7 +7781,7 @@ const ValServer = (valModules, options, callbacks) => {
           };
         }
         return {
-          error: "Session invalid or, most likely, expired. You will need to login again."
+          error: "Session invalid. You will need to login again."
         };
       }
       return {
@@ -10151,25 +10261,41 @@ const IntegratedServerJwtPayload = z.z.object({
   org: z.z.string(),
   project: z.z.string()
 });
+/**
+ * The message we show the user when their session cookie does not verify. The
+ * distinction matters: an expired session is normal and self-explanatory, while
+ * a bad signature means the cookie was tampered with or `VAL_SECRET` changed.
+ */
+function sessionErrorMessage(reason) {
+  switch (reason) {
+    case "expired":
+      return "Session expired. You will need to login again.";
+    case "malformed":
+    case "invalid-signature":
+      return "Could not verify session (invalid token). You will need to login again.";
+    case "missing-secret":
+      return "Setup is not correct: secret is missing";
+  }
+}
 async function withAuth(secret, cookies, errorMessageType, handler) {
   const cookie = cookies[internal.VAL_SESSION_COOKIE];
   if (typeof cookie === "string") {
-    const decodedToken = decodeJwt(cookie, secret);
-    if (!decodedToken) {
+    const verifiedToken = verifyJwt(cookie, secret);
+    if (!verifiedToken.success) {
       return {
         status: 401,
         json: {
-          message: "Could not verify session. You will need to login again.",
-          details: "Invalid token"
+          message: sessionErrorMessage(verifiedToken.reason),
+          details: verifiedToken.reason
         }
       };
     }
-    const verification = IntegratedServerJwtPayload.safeParse(decodedToken);
+    const verification = IntegratedServerJwtPayload.safeParse(verifiedToken.data);
     if (!verification.success) {
       return {
         status: 401,
         json: {
-          message: "Session invalid or, most likely, expired. You will need to login again.",
+          message: "Session invalid. You will need to login again.",
           details: zodValidationError.fromError(verification.error).toString()
         }
       };
@@ -12862,7 +12988,7 @@ exports.createValApiRouter = createValApiRouter;
 exports.createValModuleFileInspector = createValModuleFileInspector;
 exports.createValServer = createValServer;
 exports.currentFixHandlers = currentFixHandlers;
-exports.decodeJwt = decodeJwt;
+exports.decodeJwtWithoutVerifying = decodeJwtWithoutVerifying;
 exports.describePatchStoreProblems = describePatchStoreProblems;
 exports.downloadFileFromRemote = downloadFileFromRemote;
 exports.encodeJwt = encodeJwt;
@@ -12904,3 +13030,4 @@ exports.safeReadGit = safeReadGit;
 exports.startValLogin = startValLogin;
 exports.uploadRemoteFile = uploadRemoteFile;
 exports.validateMetadata = validateMetadata;
+exports.verifyJwt = verifyJwt;

package/dist/valbuild-server.esm.js

@@ -1902,45 +1902,142 @@ class Service {
   }
 }
 
-function decodeJwt(token, secretKey) {
+const JwtPayloadSchema = z.object({
+  sub: z.string(),
+  exp: z.number(),
+  org: z.string(),
+  project: z.string()
+})
+// NOTE: passthrough, because the session cookie payload carries more than
+// this (the val.build token, notably). This is the minimum every Val JWT has.
+.passthrough();
+/**
+ * `exp` is an absolute Unix timestamp: a token is rejected once that moment has
+ * passed, with this much slack to absorb clock drift between whoever signed the
+ * token and us.
+ */
+const CLOCK_SKEW_LEEWAY_SECONDS = 60;
+function failure(reason, message) {
+  // NOTE: deliberately never logs the token itself - it is a credential, and
+  // anything we print here ends up in the host's request logs.
+  console.debug(`Invalid JWT (${reason}): ${message}`);
+  return {
+    success: false,
+    reason,
+    message
+  };
+}
+function splitToken(token) {
   const [headerBase64, payloadBase64, signatureBase64, ...rest] = token.split(".");
   if (!headerBase64 || !payloadBase64 || !signatureBase64 || rest.length > 0) {
-    console.debug("Invalid JWT: format is not exactly {header}.{payload}.{signature}", token);
     return null;
   }
+  return {
+    headerBase64,
+    payloadBase64,
+    signatureBase64
+  };
+}
+
+/** Returns the failure if the header is not one of ours, or null if it is fine. */
+function verifyHeader(headerBase64) {
+  let parsedHeader;
   try {
-    const parsedHeader = JSON.parse(Buffer.from(headerBase64, "base64").toString("utf8"));
-    const headerVerification = JwtHeaderSchema.safeParse(parsedHeader);
-    if (!headerVerification.success) {
-      console.debug("Invalid JWT: invalid header", parsedHeader);
-      return null;
-    }
-    if (headerVerification.data.typ !== jwtHeader.typ) {
-      console.debug("Invalid JWT: invalid header typ", parsedHeader);
-      return null;
-    }
-    if (headerVerification.data.alg !== jwtHeader.alg) {
-      console.debug("Invalid JWT: invalid header alg", parsedHeader);
-      return null;
-    }
-  } catch (err) {
-    console.debug("Invalid JWT: could not parse header", err);
-    return null;
+    parsedHeader = JSON.parse(Buffer.from(headerBase64, "base64").toString("utf8"));
+  } catch {
+    return failure("malformed", "could not parse header");
   }
-  if (secretKey) {
-    const signature = crypto$1.createHmac("sha256", secretKey).update(`${headerBase64}.${payloadBase64}`).digest("base64");
-    if (signature !== signatureBase64) {
-      console.debug("Invalid JWT: invalid signature");
-      return null;
-    }
+  const headerVerification = JwtHeaderSchema.safeParse(parsedHeader);
+  if (!headerVerification.success) {
+    // NOTE: JwtHeaderSchema pins alg to HS256, so `alg: "none"` and every other
+    // algorithm-confusion header is rejected here, before we look at the
+    // signature at all.
+    return failure("malformed", "unsupported header");
   }
+  return null;
+}
+function parsePayload(payloadBase64) {
+  let parsedPayload;
   try {
-    const parsedPayload = JSON.parse(Buffer.from(payloadBase64, "base64").toString("utf8"));
-    return parsedPayload;
-  } catch (err) {
-    console.debug("Invalid JWT: could not parse payload", err);
-    return null;
+    parsedPayload = JSON.parse(Buffer.from(payloadBase64, "base64").toString("utf8"));
+  } catch {
+    return failure("malformed", "could not parse payload");
   }
+  const payloadVerification = JwtPayloadSchema.safeParse(parsedPayload);
+  if (!payloadVerification.success) {
+    return failure("malformed", "payload is not a Val JWT payload");
+  }
+  const payload = payloadVerification.data;
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  if (payload.exp + CLOCK_SKEW_LEEWAY_SECONDS <= nowSeconds) {
+    return failure("expired", "token expired");
+  }
+  return {
+    success: true,
+    data: payload
+  };
+}
+
+/**
+ * Verify a JWT that we issued with {@link encodeJwt}, and return its payload.
+ *
+ * Checks, in order: the segment count, the header (`alg` is pinned to HS256, so
+ * algorithm confusion is rejected before the signature is looked at), the HMAC
+ * (compared in constant time), the payload shape, and `exp`.
+ *
+ * There is deliberately no way to make this skip the signature check: the
+ * secret is required, and an empty one is a failure rather than a token that
+ * validates against `HMAC("")`. Use {@link decodeJwtWithoutVerifying} - and read
+ * what it says - when you genuinely do not hold the signing key.
+ */
+function verifyJwt(token, secretKey) {
+  if (!secretKey) {
+    return failure("missing-secret", "no secret key was provided");
+  }
+  const segments = splitToken(token);
+  if (!segments) {
+    return failure("malformed", "format is not exactly {header}.{payload}.{signature}");
+  }
+  const {
+    headerBase64,
+    payloadBase64,
+    signatureBase64
+  } = segments;
+  const headerFailure = verifyHeader(headerBase64);
+  if (headerFailure) {
+    return headerFailure;
+  }
+  const expectedSignature = crypto$1.createHmac("sha256", secretKey).update(`${headerBase64}.${payloadBase64}`).digest();
+  const actualSignature = Buffer.from(signatureBase64, "base64");
+  // NOTE: the length check is what makes timingSafeEqual usable at all (it
+  // throws on a length mismatch), and the length of an HMAC-SHA256 is public.
+  if (actualSignature.length !== expectedSignature.length || !crypto$1.timingSafeEqual(actualSignature, expectedSignature)) {
+    return failure("invalid-signature", "signature does not match");
+  }
+  return parsePayload(payloadBase64);
+}
+
+/**
+ * Parse a JWT's payload **without checking its signature**.
+ *
+ * The header, the payload shape and `exp` are still validated, but nothing here
+ * establishes that the token was issued by anyone in particular. Only use this
+ * for a token whose authenticity is already established by the channel it
+ * arrived on - the app token we fetch from val.build over an api-key
+ * authenticated HTTPS request is the one such case. Anything that arrives from
+ * a browser (a cookie, a header, a query parameter) must go through
+ * {@link verifyJwt}.
+ */
+function decodeJwtWithoutVerifying(token) {
+  const segments = splitToken(token);
+  if (!segments) {
+    return failure("malformed", "format is not exactly {header}.{payload}.{signature}");
+  }
+  const headerFailure = verifyHeader(segments.headerBase64);
+  if (headerFailure) {
+    return headerFailure;
+  }
+  return parsePayload(segments.payloadBase64);
 }
 function getExpire() {
   return Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 4; // 4 days
@@ -7584,7 +7681,20 @@ const ValServer = (valModules, options, callbacks) => {
     }).then(async res => {
       if (res.status === 200) {
         const token = await res.text();
-        const verification = ValAppJwtPayload.safeParse(decodeJwt(token));
+        // NOTE: this token is signed by val.build with a key we do not
+        // hold, so we cannot verify it. What stands in for a signature check
+        // is where it came from: the POST above, authenticated with the
+        // project's api key, to the configured `valBuildUrl`. It is not user
+        // input - but it is only as trustworthy as that host and that
+        // channel, and `valBuildUrl` is overridable (`opts.valBuildUrl`,
+        // `VAL_BUILD_URL`) and not required to be https. Point it at a plain
+        // http host and this payload - which is re-signed into the session
+        // cookie below - is whatever the network says it is.
+        const decoded = decodeJwtWithoutVerifying(token);
+        if (!decoded.success) {
+          return null;
+        }
+        const verification = ValAppJwtPayload.safeParse(decoded.data);
         if (!verification.success) {
           return null;
         }
@@ -7616,8 +7726,8 @@ const ValServer = (valModules, options, callbacks) => {
       }
     }
     if (typeof cookie === "string") {
-      const decodedToken = decodeJwt(cookie, options.valSecret);
-      if (!decodedToken) {
+      const verifiedToken = verifyJwt(cookie, options.valSecret);
+      if (!verifiedToken.success) {
         if (serverOps instanceof ValOpsFS) {
           return {
             error: null,
@@ -7625,10 +7735,10 @@ const ValServer = (valModules, options, callbacks) => {
           };
         }
         return {
-          error: "Could not verify session (invalid token). You will need to login again."
+          error: sessionErrorMessage(verifiedToken.reason)
         };
       }
-      const verification = IntegratedServerJwtPayload.safeParse(decodedToken);
+      const verification = IntegratedServerJwtPayload.safeParse(verifiedToken.data);
       if (!verification.success) {
         if (serverOps instanceof ValOpsFS) {
           return {
@@ -7637,7 +7747,7 @@ const ValServer = (valModules, options, callbacks) => {
           };
         }
         return {
-          error: "Session invalid or, most likely, expired. You will need to login again."
+          error: "Session invalid. You will need to login again."
         };
       }
       return {
@@ -10117,25 +10227,41 @@ const IntegratedServerJwtPayload = z.object({
   org: z.string(),
   project: z.string()
 });
+/**
+ * The message we show the user when their session cookie does not verify. The
+ * distinction matters: an expired session is normal and self-explanatory, while
+ * a bad signature means the cookie was tampered with or `VAL_SECRET` changed.
+ */
+function sessionErrorMessage(reason) {
+  switch (reason) {
+    case "expired":
+      return "Session expired. You will need to login again.";
+    case "malformed":
+    case "invalid-signature":
+      return "Could not verify session (invalid token). You will need to login again.";
+    case "missing-secret":
+      return "Setup is not correct: secret is missing";
+  }
+}
 async function withAuth(secret, cookies, errorMessageType, handler) {
   const cookie = cookies[VAL_SESSION_COOKIE];
   if (typeof cookie === "string") {
-    const decodedToken = decodeJwt(cookie, secret);
-    if (!decodedToken) {
+    const verifiedToken = verifyJwt(cookie, secret);
+    if (!verifiedToken.success) {
       return {
         status: 401,
         json: {
-          message: "Could not verify session. You will need to login again.",
-          details: "Invalid token"
+          message: sessionErrorMessage(verifiedToken.reason),
+          details: verifiedToken.reason
         }
       };
     }
-    const verification = IntegratedServerJwtPayload.safeParse(decodedToken);
+    const verification = IntegratedServerJwtPayload.safeParse(verifiedToken.data);
     if (!verification.success) {
       return {
         status: 401,
         json: {
-          message: "Session invalid or, most likely, expired. You will need to login again.",
+          message: "Session invalid. You will need to login again.",
           details: fromError(verification.error).toString()
         }
       };
@@ -12800,4 +12926,4 @@ function readCapturedReport(snapshotDir) {
   return JSON.parse(fs.readFileSync(reportPath, "utf-8"));
 }
 
-export { DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_MAX_DURATION, DEFAULT_LOGIN_POLL_INTERVAL, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, classifyJsonValuesOp, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValModuleFileInspector, createValServer, currentFixHandlers, decodeJwt, 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, loadValModules, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, readCapturedReport, readPatchStore, rebaseContentOp, replaySnapshot, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata };
+export { DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_MAX_DURATION, DEFAULT_LOGIN_POLL_INTERVAL, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, classifyJsonValuesOp, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValModuleFileInspector, createValServer, 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, 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.111.0",
+  "version": "0.113.0",
   "devDependencies": {
     "@prettier/sync": "^0.6.1",
     "@types/jest": "^30.0.0"
@@ -29,9 +29,9 @@
     "typescript": "^6.0.3",
     "zod": "^4.4.3",
     "zod-validation-error": "^5.0.0",
-    "@valbuild/core": "0.111.0",
-    "@valbuild/shared": "0.111.0",
-    "@valbuild/ui": "0.111.0"
+    "@valbuild/shared": "0.113.0",
+    "@valbuild/ui": "0.113.0",
+    "@valbuild/core": "0.111.0"
   },
   "engines": {
     "node": "^20.19.0 || >=22"