Merge branch 'main' into node-page-updates

Author: thisisjofrank

_includes/doc.tsx

@@ -2,64 +2,54 @@ import renderCommand from "./renderCommand.tsx";
 
 export const layout = "layout.tsx";
 
-export const ogImage = (data: Lume.Data) => {
-  return data.url + "/index.png";
-};
+export const ogImage = (data: Lume.Data) => `${data.url}/index.png`;
 
 export default function Doc(data: Lume.Data, helpers: Lume.Helpers) {
-  let file = data.page.sourcePath;
-  const sidebar = data.sidebar;
-  let renderedCommand = null;
-
-  if (data.command) {
-    const { rendered, toc } = renderCommand(data.command, helpers);
-    renderedCommand = rendered;
-    data.toc = toc.concat(...data.toc);
-  }
-
+  // Flags and simple derivations
+  const API_LANDING = new Set(["/api/deno/", "/api/web/", "/api/node/"]);
   const isReference = data.url.startsWith("/api/");
-  const isApiLandingPage = ["/api/deno/", "/api/web/", "/api/node/"].includes(
-    data.url,
+  const isApiLandingPage = API_LANDING.has(data.url);
+  const isExampleScript = Boolean(
+    (data.page.data.content as { type?: string })?.type,
   );
-  const isExamples = data.url.startsWith("/examples/");
-  const isExampleScript = (data.page.data.content as { type?: string })?.type;
   const isLintRule = data.url.startsWith("/lint/rules/");
-  const isHome = data.url === "/";
 
-  const hasBreadcrumbs = !isExamples && !isHome &&
-    !(isReference && !isApiLandingPage);
+  // Compute file path used by Feedback component
+  const file = isLintRule
+    ? `/lint/rules/${encodeURIComponent(data.title ?? "")}.md`
+    : data.page.sourcePath;
 
-  if (isLintRule) {
-    file = `/lint/rules/${encodeURIComponent(data.title ?? "")}.md`;
+  // Render command block and merge its TOC if present
+  let renderedCommand: unknown = null;
+  if (data.command) {
+    const { rendered, toc } = renderCommand(data.command, helpers);
+    renderedCommand = rendered;
+    data.toc = toc.concat(...data.toc);
   }
 
   function getTocCtx(
-    d: Lume.Data,
+    d: unknown,
   ): { document_navigation: unknown; document_navigation_str: string } | null {
-    const ch: unknown = (d as unknown as { children?: unknown })?.children;
-    if (ch && typeof ch === "object" && "props" in ch) {
-      const props: unknown = (ch as { props?: unknown }).props;
-      if (props && typeof props === "object" && "data" in props) {
-        const pdata: unknown = (props as { data?: unknown }).data;
-        if (pdata && typeof pdata === "object" && "toc_ctx" in pdata) {
-          const toc: unknown = (pdata as { toc_ctx?: unknown }).toc_ctx;
-          if (
-            toc && typeof toc === "object" &&
-            "document_navigation" in toc &&
-            "document_navigation_str" in toc
-          ) {
-            const t = toc as {
-              document_navigation: unknown;
-              document_navigation_str: string;
-            };
-            return t;
-          }
-        }
-      }
+    type Toc = {
+      document_navigation: unknown;
+      document_navigation_str: string;
+    };
+    const tocCtx: unknown = (d as {
+      children?: { props?: { data?: { toc_ctx?: unknown } } };
+    })?.children?.props?.data?.toc_ctx;
+    if (
+      tocCtx &&
+      typeof tocCtx === "object" &&
+      "document_navigation" in tocCtx &&
+      "document_navigation_str" in tocCtx
+    ) {
+      return tocCtx as Toc;
     }
     return null;
   }
 
+  const tocCtx = getTocCtx(data);
+
   return (
     <>
       <main
@@ -107,17 +97,12 @@ export default function Doc(data: Lume.Data, helpers: Lume.Helpers) {
           <data.comp.Feedback file={file} />
         </div>
       </main>
-      {(() => {
-        const tocCtx = getTocCtx(data);
-        return isReference && tocCtx
-          ? (
-            <data.comp.RefToc
-              documentNavigation={tocCtx.document_navigation}
-              documentNavigationStr={tocCtx.document_navigation_str}
-            />
-          )
-          : null;
-      })()}
+      {isReference && tocCtx && (
+        <data.comp.RefToc
+          documentNavigation={tocCtx.document_navigation}
+          documentNavigationStr={tocCtx.document_navigation_str}
+        />
+      )}
     </>
   );
 }

deploy/classic/api/runtime-node.md

@@ -32,9 +32,6 @@ const server = createServer((req, res) => {
 server.listen(8080);
 ```
 
-_You can see this example live here:
-https://dash.deno.com/playground/node-specifiers_
-
 When using `node:` specifiers, all other features of Deno Deploy Classic are
 still available. For example, you can use `Deno.env` to access environment
 variables even when using Node.js modules. You can also import other ESM modules

runtime/fundamentals/security.md

@@ -106,8 +106,8 @@ format, where each line is an object with the following keys:
 - `value`: the value that the permission was accessed with, or `null` if it was
   accessed with no value
 
-A schema for this can be found
-[here](https://github.com/denoland/deno/blob/main/cli/schemas/permission-audit.v1.json).
+A schema for this can be found in
+[permission-audit.v1.json](https://github.com/denoland/deno/blob/main/cli/schemas/permission-audit.v1.json).
 
 In addition, this env var can be combined with the above-mentioned
 `DENO_TRACE_PERMISSIONS`, which then adds a new `stack` field to the entries
@@ -458,11 +458,11 @@ code from. This is true for both static and dynamic imports.
 
 If you want to dynamically import code, either using the `import()` or the
 `new Worker()` APIs, additional permissions need to be granted. Importing from
-the local file system [requires `--allow-read`](#file-system-read-access), but
-Deno also allows to import from `http:` and `https:` URLs. In such case you will
-need to specify an explicit `--allow-import` flag:
+the local file system [requires `--allow-read`](#file-system-access), but Deno
+also allows to import from `http:` and `https:` URLs. In such case you will need
+to specify an explicit `--allow-import` flag:
 
-```
+```sh
 # allow importing code from `https://example.com`
 $ deno run --allow-import=example.com main.ts
 ```
@@ -476,12 +476,12 @@ By default Deno allows importing sources from following hosts:
 - `raw.githubusercontent.com`
 - `gist.githubusercontent.com`
 
-**Imports are only allowed using HTTPS**
+Imports are only allowed using HTTPS.
 
 This allow list is applied by default for static imports, and by default to
 dynamic imports if the `--allow-import` flag is specified.
 
-```
+```sh
 # allow dynamically importing code from `https://deno.land`
 $ deno run --allow-import main.ts
 ```
@@ -515,3 +515,63 @@ using all of these when executing arbitrary untrusted code:
 - Use OS provided sandboxing mechanisms like `chroot`, `cgroups`, `seccomp`,
   etc.
 - Use a sandboxed environment like a VM or MicroVM (gVisor, Firecracker, etc).
+
+## Permission broker
+
+For centralized and policy-driven permission decisions, Deno can delegate all
+permission checks to an external broker process. Enable this by setting the
+`DENO_PERMISSION_BROKER_PATH` environment variable to a path that Deno will use
+to connect to the broker:
+
+- On Unix-like systems: a Unix domain socket path (for example,
+  `/tmp/deno-perm.sock`).
+- On Windows: a named pipe (for example, `\\.\pipe\deno-perm-broker`).
+
+When a permission broker is active:
+
+- All `--allow-*` and `--deny-*` flags are ignored.
+- Interactive permission prompts are not shown (equivalent to non-interactive
+  mode).
+- Every permission check is sent to the broker; the broker must reply with a
+  decision for each request.
+
+If anything goes wrong during brokering (for example: Deno cannot connect to the
+socket/pipe, messages are malformed, arrive out of order, IDs do not match, or
+the connection closes unexpectedly), Deno immediately terminates the process to
+preserve integrity and prevent permission escalation.
+
+The request/response message shapes are versioned and defined by JSON Schemas:
+
+- Request schema:
+  [permission-broker-request.v1.json](https://github.com/denoland/deno/blob/main/cli/schemas/permission-broker-request.v1.json)
+- Response schema:
+  [permission-broker-response.v1.json](https://github.com/denoland/deno/blob/main/cli/schemas/permission-broker-response.v1.json)
+
+Each request contains a version (`v`), the Deno process ID (`pid`), a unique
+monotonic request `id`, a timestamp (`datetime`, RFC 3339), the `permission`
+name, and an optional `value` depending on permission type. The response must
+echo the `id` and include a `result` of either `"grant"` or `"deny"`. When
+denied, a human-readable `reason` may be included.
+
+Example message flow:
+
+```text
+-> req {"v":1,"pid":10234,"id":1,"datetime":"2025-01-01T00:00:00.000Z","permission":"read","value":"./run/permission_broker/scratch.txt"}
+<- res {"id":1,"result":"grant"}
+-> req {"v":1,"pid":10234,"id":2,"datetime":"2025-01-01T00:00:01.000Z","permission":"read","value":"./run/permission_broker/scratch.txt"}
+<- res {"id":2,"result":"grant"}
+-> req {"v":1,"pid":10234,"id":3,"datetime":"2025-01-01T00:00:02.000Z","permission":"read","value":"./run/permission_broker/log.txt"}
+<- res {"id":3,"result":"grant"}
+-> req {"v":1,"pid":10234,"id":4,"datetime":"2025-01-01T00:00:03.000Z","permission":"write","value":"./run/permission_broker/log.txt"}
+<- res {"id":4,"result":"grant"}
+-> req {"v":1,"pid":10234,"id":5,"datetime":"2025-01-01T00:00:04.000Z","permission":"env","value":null}
+<- res {"id":5,"result":"deny","reason":"Environment access is denied."}
+```
+
+:::caution Advanced use only
+
+Using a permission broker changes Deno’s decision authority: CLI flags and
+prompts no longer apply. Ensure your broker process is resilient, audited, and
+available before enabling `DENO_PERMISSION_BROKER_PATH`.
+
+:::