@jsenv/server 17.1.1 → 17.3.0

package/src/plugins/cookies/cookie.js

@@ -0,0 +1,77 @@
+// https://bun.sh/docs/api/cookie
+
+export const COOKIE = {
+  from: (name, value, options = {}) => {
+    return { name, value, options };
+  },
+  parse: (cookieString) => {
+    const parts = cookieString.split("; ");
+    const [nameValue, ...attributes] = parts;
+    const [name, value] = nameValue.split("=");
+    const options = {};
+    for (const attr of attributes) {
+      const [key, val] = attr.split("=");
+      if (key === "expires") {
+        options.expires = new Date(val);
+        continue;
+      }
+      if (key === "path") {
+        options.path = val;
+        continue;
+      }
+      if (key === "domain") {
+        options.domain = val;
+        continue;
+      }
+      if (key === "secure") {
+        options.secure = true;
+        continue;
+      }
+      if (key === "httponly") {
+        options.httpOnly = true;
+        continue;
+      }
+    }
+
+    return { name, value, options };
+  },
+  stringify: ({ name, value, options }) => {
+    let str = `${name}=${value}`;
+    if (options.expires) {
+      str += `; Expires=${options.expires.toUTCString()}`;
+    }
+    if (options.maxAge !== undefined) {
+      str += `; Max-Age=${options.maxAge}`;
+    }
+    if (options.path) {
+      str += `; Path=${options.path}`;
+    }
+    if (options.domain) {
+      str += `; Domain=${options.domain}`;
+    }
+    if (options.sameSite) {
+      str += `; SameSite=${options.sameSite}`;
+    }
+    if (options.secure) {
+      str += "; Secure";
+    }
+    if (options.httpOnly) {
+      str += "; HttpOnly";
+    }
+    return str;
+  },
+  toSetCookieHeaders: (cookies) => {
+    const headers = {};
+    for (const cookie of cookies) {
+      const value = COOKIE.stringify(cookie);
+      if (headers["set-cookie"] === undefined) {
+        headers["set-cookie"] = value;
+      } else if (Array.isArray(headers["set-cookie"])) {
+        headers["set-cookie"].push(value);
+      } else {
+        headers["set-cookie"] = [headers["set-cookie"], value];
+      }
+    }
+    return headers;
+  },
+};

package/src/plugins/cookies/server_plugin_response_cookies.js

@@ -0,0 +1,30 @@
+import { COOKIE } from "./cookie.js";
+
+export const serverPluginResponseCookies = () => {
+  return {
+    name: "jsenv:response_cookies",
+    augmentRouteFetchSecondArg: (request, fetchSecondArg) => {
+      const responseCookies = {
+        set: (name, value, options = {}) => {
+          fetchSecondArg.injectResponseHeader(
+            "set-cookie",
+            COOKIE.stringify(COOKIE.from(name, value, options)),
+          );
+        },
+        delete: (name, options = {}) => {
+          fetchSecondArg.injectResponseHeader(
+            "set-cookie",
+            COOKIE.stringify(
+              COOKIE.from(name, "", {
+                ...options,
+                expires: new Date(0),
+              }),
+            ),
+          );
+        },
+      };
+
+      return { responseCookies };
+    },
+  };
+};

package/src/plugins/route_inspector/client/code_block.js

@@ -113,7 +113,9 @@
     }
   }
 
-  customElements.define("clipboard-copy", ClipboardCopy);
+  if (!customElements.get("clipboard-copy")) {
+    customElements.define("clipboard-copy", ClipboardCopy);
+  }
 
   const addToClipboard = async (text) => {
     const type = "text/plain";

package/src/plugins/route_inspector/client/route_inspector.html

@@ -42,6 +42,13 @@
         --border-color: #e0e0e0;
         --primary-color: #1976d2;
         --secondary-color: #f5f5f5;
+        --forbidden-bg-color: #fff8f0;
+        --forbidden-border-color: #cc8800;
+        --forbidden-badge-bg: #fff3cc;
+        --forbidden-badge-color: #7a5000;
+        --admin-badge-bg: #f0f4ff;
+        --admin-badge-border-color: #5c7cfa;
+        --admin-badge-color: #2a4bbf;
       }
       :root[data-theme="dark"] {
         --background-color: #121212;
@@ -49,6 +56,13 @@
         --border-color: #333;
         --primary-color: #4f9eff;
         --secondary-color: #1e1e1e;
+        --forbidden-bg-color: #1e1500;
+        --forbidden-border-color: #8a6000;
+        --forbidden-badge-bg: #3a2800;
+        --forbidden-badge-color: #f0c060;
+        --admin-badge-bg: #0d1a3a;
+        --admin-badge-border-color: #3b5bdb;
+        --admin-badge-color: #91a7ff;
       }
 
       :root[data-theme="dark"] a {
@@ -467,6 +481,42 @@
         --method-color: var(--method-delete-color);
       }
 
+      .route_details[data-forbidden] {
+        background: var(--forbidden-bg-color);
+        border-color: var(--forbidden-border-color);
+        opacity: 0.85;
+      }
+      .route_details[data-forbidden] .route_method {
+        opacity: 0.7;
+        filter: grayscale(60%);
+      }
+      .route_forbidden_badge {
+        margin-right: 6px;
+        padding: 3px 8px;
+        color: var(--forbidden-badge-color);
+        font-weight: 600;
+        font-size: 12px;
+        white-space: nowrap;
+        background: var(--forbidden-badge-bg);
+        border: 1px solid var(--forbidden-border-color);
+        border-radius: 4px;
+      }
+      .route_admin_badge {
+        margin-right: 6px;
+        padding: 3px 8px;
+        color: var(--admin-badge-color);
+        font-weight: 600;
+        font-size: 12px;
+        white-space: nowrap;
+        background: var(--admin-badge-bg);
+        border: 1px solid var(--admin-badge-border-color);
+        border-radius: 4px;
+      }
+      .route_forbidden_content {
+        color: var(--forbidden-badge-color);
+        font-style: italic;
+      }
+
       .route_owner_name {
         padding: 4px 8px;
         color: #666;
@@ -1388,6 +1438,8 @@
         websocket,
         clientCodeExample,
         declarationSource,
+        forbidden,
+        visibleBecauseAdmin,
       }) => {
         const [selectedMethod] = useUrlStringParam("method");
         const [selectedPackageName] = usePackageUrlStringParam();
@@ -1400,11 +1452,16 @@
           return null;
         }
 
-        return html`<details class="route_details" data-method="${method}">
+        return html`<details
+            class="route_details"
+            data-method="${method}"
+            data-forbidden="${forbidden || undefined}"
+            data-admin-visible="${visibleBecauseAdmin || undefined}"
+          >
             <summary class="route_summary_container">
               <span class="route_method">${method}</span>
               <p class="route_resource">${resource}</p>
-              ${method === "GET"
+              ${method === "GET" && !forbidden
                 ? html`<a
                       style="display:inline-flex; margin-left: 5px;"
                       href="${resource}"
@@ -1412,25 +1469,45 @@
                     /></a>`
                 : null}
               <span style="flex:1"></span>
+              ${visibleBecauseAdmin
+                ? html`<span
+                      class="route_admin_badge"
+                      title="This route is only visible because the server was started with canExposeSensitiveData"
+                      >&#128274; admin only</span
+                    >`
+                : null}
+              ${forbidden && !visibleBecauseAdmin
+                ? html`<span class="route_forbidden_badge"
+                      >&#128274; access denied</span
+                    >`
+                : null}
               <${RouteBadge} meta="${meta}" />
               <span class="summary_marker">
                 <${ArrowDown} />
               </span>
             </summary>
-            <${RouteDetailsContent}
-              method="${method}"
-              resource="${resource}"
-              description="${description}"
-              availableMediaTypes="${availableMediaTypes}"
-              availableLanguages="${availableLanguages}"
-              availableVersions="${availableVersions}"
-              availableEncodings="${availableEncodings}"
-              acceptedMediaTypes="${acceptedMediaTypes}"
-              websocket="${websocket}"
-              clientCodeExample="${clientCodeExample}"
-              declarationSource="${declarationSource}"
-              meta="${meta}"
-            />
+            ${!forbidden
+              ? html`<${RouteDetailsContent}
+                    method="${method}"
+                    resource="${resource}"
+                    description="${description}"
+                    availableMediaTypes="${availableMediaTypes}"
+                    availableLanguages="${availableLanguages}"
+                    availableVersions="${availableVersions}"
+                    availableEncodings="${availableEncodings}"
+                    acceptedMediaTypes="${acceptedMediaTypes}"
+                    websocket="${websocket}"
+                    clientCodeExample="${clientCodeExample}"
+                    declarationSource="${declarationSource}"
+                    meta="${meta}"
+                  />`
+              : html`<div class="route_details_content route_forbidden_content">
+                    <p>
+                      ${visibleBecauseAdmin
+                        ? "This route is only visible because the server was started with canExposeSensitiveData. Access is denied with the current permissions."
+                        : "You do not have the required permissions to access this route."}
+                    </p>
+                  </div>`}
           </details>`;
       };
 
@@ -1561,26 +1638,26 @@
           const websocketScheme =
             self.location.protocol === "https:" ? "wss" : "ws";
           const websocketOrigin = `${websocketScheme}://${self.location.host}`;
-          jsSource = /*js */ `
-                const websocket = new WebSocket("${websocketOrigin}${resource}");
-                websocket.onerror = () => {
-                  console.error("Failed to connect to websocket endpoint");
-                };
-                websocket.onopen = () => {
-                  console.info("Connected to websocket endpoint")
-                };
-                websocket.onmessage = (event) => {
-                  console.log("Received message", event.data);
-                };
-                `;
+          jsSource = `
+const websocket = new WebSocket("${websocketOrigin}${resource}");
+websocket.onerror = () => {
+  console.error("Failed to connect to websocket endpoint");
+};
+websocket.onopen = () => {
+  console.info("Connected to websocket endpoint");
+};
+websocket.onmessage = (event) => {
+  console.log("Received message", event.data);
+};
+          `;
         } else {
           let fetchLine;
           if (method === "GET") {
             fetchLine = `const response = await window.fetch("${resource}");`;
           } else {
             fetchLine = `const response = await window.fetch("${resource}", {
-        method: "${method}",
-      }`;
+  method: "${method}",
+}`;
           }
           let readResponseLine;
           if (availableMediaTypes.includes("application/json")) {
@@ -1589,10 +1666,10 @@
             readResponseLine = `const text = await response.text();`;
           }
 
-          jsSource = /*js */ `
-      ${fetchLine}
-      ${readResponseLine}
-                `;
+          jsSource = `
+${fetchLine};
+${readResponseLine};
+          `;
         }
 
         return html`<code-block lang="js" data-escaped data-copy-button

package/src/plugins/route_inspector/server_plugin_route_inspector.js

@@ -28,9 +28,10 @@ export const serverPluginRouteInspector = ({ canExposeSensitiveData }) => {
         availableMediaTypes: ["application/json"],
         description: "Get the routes available on this server in JSON.",
         declarationSource: import.meta.url,
-        fetch: (request, helpers) => {
-          const routeJSON = helpers.router.inspect({
+        fetch: async (request, helpers) => {
+          const routeJSON = await helpers.router.inspect({
             canExposeSensitiveData,
+            fetchSecondArg: helpers,
           });
           return Response.json(routeJSON);
         },

package/src/plugins/server_plugins_controller.js

@@ -9,6 +9,7 @@ export const createServerPluginsController = async (serverPlugins) => {
         serverListening: { type: "hook" },
         redirectRequest: { type: "hook" },
         augmentRouteFetchSecondArg: { type: "hook" },
+        grantPermissions: { type: "hook" },
         handleError: { type: "hook" },
         onResponsePush: { type: "hook" },
         injectResponseProperties: { type: "hook" },

package/src/plugins_controller.js

@@ -297,12 +297,55 @@ export const createPluginsController = async ({
     callHooksUntil,
     callAsyncHooks,
     callAsyncHooksUntil,
+    // callAsyncHooksWhile(hookName, info, callback)
+    // Calls hooks one by one, passing each return value to callback.
+    // Stops as soon as callback returns false.
+    callAsyncHooksWhile: async (hookName, info, callback) => {
+      const hookSet = hookSetMap.get(hookName);
+      if (!hookSet) {
+        return;
+      }
+      for (const hook of hookSet) {
+        const returnValue = await callAsyncHook(hook, info);
+        const shouldContinue = await callback(returnValue);
+        if (!shouldContinue) {
+          return;
+        }
+      }
+    },
+
+    // createAsyncHookIterator(hookName, info)
+    // Returns an async function that calls the next hook on each invocation.
+    // Returns { done: true } when all hooks have been called.
+    // Allows callers to maintain a shared cursor across multiple consumers.
+    createAsyncHookIterator: (hookName, info) => {
+      const hookSet = hookSetMap.get(hookName);
+      if (!hookSet) {
+        return async () => ({ done: true, value: undefined });
+      }
+      const iterator = hookSet.values();
+      return async () => {
+        const { done, value: hook } = iterator.next();
+        if (done) {
+          return { done: true, value: undefined };
+        }
+        const value = await callAsyncHook(hook, info);
+        return { done: false, value };
+      };
+    },
 
     getPluginMeta: (pluginName) => meta[pluginName],
     getMeta: () => meta,
     getLastPluginUsed: () => lastPluginUsed,
     getCurrentPlugin: () => currentPlugin,
     getCurrentHookName: () => currentHookName,
+    destroyAllPlugins: async () => {
+      for (const plugin of activePlugins) {
+        if (plugin.destroy) {
+          await plugin.destroy();
+        }
+      }
+    },
   };
 };
 

package/src/router/router.js

@@ -32,6 +32,7 @@ export const createRouter = (
 ) => {
   const logger = createLogger({ logLevel });
   const routeSet = new Set();
+  let someRouteHasPermissions = false;
 
   const constructAvailableEndpoints = () => {
     // TODO: memoize
@@ -173,6 +174,12 @@ export const createRouter = (
   for (const routeDescription of routeDescriptionArray) {
     const route = createRoute(routeDescription);
     routeSet.add(route);
+    if (
+      route.permissionsRequired !== undefined ||
+      route.permissionsToSee !== undefined
+    ) {
+      someRouteHasPermissions = true;
+    }
   }
 
   const match = async (request, fetchSecondArg) => {
@@ -340,6 +347,26 @@ It should be should be one of route.${routePropertyName}: ${availableValues.join
         if (!resourceMatchResult) {
           continue;
         }
+        // permissions check — done before method/media-type/upgrade checks so that
+        // a hidden route does not leak its existence via 405/415/426 responses.
+        // If the route's method would not have matched anyway we skip silently (no
+        // wouldHaveMatched contribution). If the method would have matched we return
+        // the denied response so the caller gets 404 or 403.
+        if (someRouteHasPermissions) {
+          const { permissionsRequired, permissionsToSee } = route;
+          const denied = await checkRouteAccess(
+            permissionsRequired,
+            permissionsToSee,
+            request,
+            fetchSecondArg,
+          );
+          if (denied) {
+            if (route.matchMethod(request.method)) {
+              return denied;
+            }
+            continue;
+          }
+        }
         if (!route.matchMethod(request.method)) {
           if (!route.isFallback) {
             wouldHaveMatched.methodSet.add(route.method);
@@ -525,10 +552,68 @@ It should be should be one of route.${routePropertyName}: ${availableValues.join
 
     return matchRoutes(request);
   };
-  const inspect = ({ canExposeSensitiveData }) => {
-    // I want all the info I can gather about the routes
+  const inspect = async ({ canExposeSensitiveData, fetchSecondArg }) => {
     const data = [];
     for (const route of routeSet) {
+      if (someRouteHasPermissions) {
+        const { permissionsRequired, permissionsToSee } = route;
+        // route has no permission config → hidden from inspector
+        // (unless canExposeSensitiveData is set, in which case we show it as admin-only visible)
+        if (
+          permissionsRequired === undefined &&
+          permissionsToSee === undefined
+        ) {
+          if (!canExposeSensitiveData) {
+            continue;
+          }
+          const routeData = route.toJSON({ canExposeSensitiveData });
+          routeData.visibleBecauseAdmin = true;
+          data.push(routeData);
+          continue;
+        }
+        // anyone can access → always visible
+        if (
+          permissionsRequired !== undefined &&
+          permissionsRequired.length > 0
+        ) {
+          if (fetchSecondArg) {
+            const granted =
+              await fetchSecondArg.hasPermissions(permissionsRequired);
+            if (!granted) {
+              // determine if route is normally visible (permissionsToSee satisfied)
+              let normallyCanSee;
+              if (permissionsToSee === undefined) {
+                normallyCanSee = false;
+              } else {
+                const permsSet = await fetchSecondArg.getAllPermissions();
+                normallyCanSee =
+                  permissionsToSee.length === 0 ||
+                  permissionsSatisfy(permsSet, permissionsToSee);
+              }
+              if (!normallyCanSee && !canExposeSensitiveData) {
+                continue;
+              }
+              const routeData = route.toJSON({ canExposeSensitiveData });
+              routeData.forbidden = true;
+              if (!normallyCanSee) {
+                routeData.visibleBecauseAdmin = true;
+              }
+              data.push(routeData);
+              continue;
+            }
+          } else if (permissionsToSee === undefined) {
+            if (!canExposeSensitiveData) {
+              // no request context and route is not publicly visible
+              continue;
+            }
+            const routeData = route.toJSON({ canExposeSensitiveData });
+            routeData.forbidden = true;
+            routeData.visibleBecauseAdmin = true;
+            data.push(routeData);
+            continue;
+          }
+        }
+      }
       data.push(route.toJSON({ canExposeSensitiveData }));
     }
     return data;
@@ -581,6 +666,8 @@ const createRoute = ({
   headers,
   service,
   serverPlugin,
+  permissionsRequired,
+  permissionsToSee,
   availableMediaTypes = [],
   availableLanguages = [],
   availableVersions = [],
@@ -631,6 +718,8 @@ const createRoute = ({
     description,
     service,
     serverPlugin,
+    permissionsRequired,
+    permissionsToSee,
     availableMediaTypes,
     availableLanguages,
     availableVersions,
@@ -718,6 +807,59 @@ const createRoute = ({
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 const isRedirectStatus = (status) => REDIRECT_STATUSES.has(status);
 
+// Returns a denied response if the request does not satisfy route access/visible config.
+// Returns null if access is granted.
+const checkRouteAccess = async (
+  permissionsRequired,
+  permissionsToSee,
+  request,
+  fetchSecondArg,
+) => {
+  // No permissionsRequired declared → route is hidden by default
+  if (permissionsRequired === undefined) {
+    return createRouteNotFoundResponse(request);
+  }
+  // permissionsRequired: [] → anyone can access
+  if (permissionsRequired.length === 0) {
+    return null;
+  }
+  // early-exit permission check (stops as soon as rule is satisfied)
+  const granted = await fetchSecondArg.hasPermissions(permissionsRequired);
+  if (granted) {
+    return null;
+  }
+  // access denied — decide between 404 and 403
+  if (permissionsToSee === undefined) {
+    return createRouteNotFoundResponse(request);
+  }
+  // permissionsToSee check uses full permissions (already accumulated from hasPermissions call above)
+  const permsSet = await fetchSecondArg.getAllPermissions();
+  if (
+    permissionsToSee.length === 0 ||
+    permissionsSatisfy(permsSet, permissionsToSee)
+  ) {
+    return createForbiddenResponse(request);
+  }
+  return createRouteNotFoundResponse(request);
+};
+
+const permissionsSatisfy = (permissionsSet, permissionsRequired) => {
+  for (const p of permissionsRequired) {
+    if (!permissionsSet.has(p)) {
+      return false;
+    }
+  }
+  return true;
+};
+
+const createForbiddenResponse = () => {
+  return {
+    status: 403,
+    statusText: "Forbidden",
+    headers: {},
+  };
+};
+
 const isRequestBodyMediaTypeSupported = (request, { acceptedMediaTypes }) => {
   const requestBodyContentType = request.headers["content-type"];
   if (!requestBodyContentType) {