app: frontend: Add manifest-declared legal documents

Expose packaged legal documents through a validated desktop IPC capability.
This lets downstream builds declare legal content without forking the UI.

Co-authored-by: René Dudfield <renedudfield@microsoft.com>

Author: joaquimrocha

app/app-build-manifest.json

@@ -13,5 +13,17 @@
       "name": "prometheus",
       "archive": "https://github.com/headlamp-k8s/plugins/releases/download/prometheus-0.9.1/prometheus-0.9.1.tar.gz"
     }
+  ],
+  "legalDocuments": [
+    {
+      "id": "license",
+      "title": "License",
+      "file": "LICENSE"
+    },
+    {
+      "id": "notices",
+      "title": "Third-party notices",
+      "file": "NOTICE"
+    }
   ]
 }

app/electron/legal-documents.ts

@@ -0,0 +1,126 @@
+/*
+ * Copyright 2025 The Kubernetes Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** A legal document declared in the application build manifest. */
+export interface LegalDocument {
+  /** Stable identifier used when requesting the document over IPC. */
+  id: string;
+  /** Human-readable title shown in the application. */
+  title: string;
+  /** Resource filename relative to the packaged application resources directory. */
+  file: string;
+}
+
+/** Public metadata for a legal document exposed to the renderer. */
+export type LegalDocumentSummary = Pick<LegalDocument, 'id' | 'title'>;
+
+/** Result returned when the renderer requests legal document content. */
+export interface LegalDocumentResult {
+  /** Whether the requested document was read successfully. */
+  success: boolean;
+  /** Document text when the request succeeds. */
+  content?: string;
+  /** User-facing failure reason when the request fails. */
+  error?: string;
+}
+
+const VALID_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/**
+ * Validates legal documents from parsed application build metadata.
+ *
+ * @param packageConfig - Parsed application build manifest content.
+ * @returns Valid manifest-declared legal documents.
+ */
+export function getLegalDocuments(packageConfig: unknown): LegalDocument[] {
+  if (typeof packageConfig !== 'object' || packageConfig === null) {
+    return [];
+  }
+
+  const configuredDocuments = (packageConfig as { legalDocuments?: unknown }).legalDocuments;
+
+  if (!Array.isArray(configuredDocuments)) {
+    return [];
+  }
+
+  return configuredDocuments.filter((document): document is LegalDocument => {
+    if (typeof document !== 'object' || document === null) {
+      return false;
+    }
+    const { id, title, file } = document as Partial<LegalDocument>;
+    return (
+      typeof id === 'string' &&
+      VALID_ID.test(id) &&
+      typeof title === 'string' &&
+      title.length > 0 &&
+      title.length <= 128 &&
+      typeof file === 'string' &&
+      file.length > 0 &&
+      file.length <= 255 &&
+      !file.includes('/') &&
+      !file.includes('\\') &&
+      file !== '.' &&
+      file !== '..'
+    );
+  });
+}
+
+/**
+ * Loads legal document declarations from an application build manifest.
+ *
+ * @param packagePath - Path to the application build manifest JSON file.
+ * @returns Valid legal document declarations, or an empty array when loading fails.
+ */
+export function loadLegalDocuments(packagePath: string): LegalDocument[] {
+  try {
+    return getLegalDocuments(JSON.parse(fs.readFileSync(packagePath, 'utf8')));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Reads one configured legal document from packaged application resources.
+ *
+ * @param resourcesPath - Root directory containing packaged resources.
+ * @param documents - Valid legal document declarations.
+ * @param id - Untrusted document identifier received over IPC.
+ * @returns Document content on success, otherwise a stable failure result.
+ */
+export function readLegalDocument(
+  resourcesPath: string,
+  documents: LegalDocument[],
+  id: unknown
+): LegalDocumentResult {
+  const document = typeof id === 'string' ? documents.find(item => item.id === id) : undefined;
+  if (!document) {
+    return { success: false, error: 'Unknown legal document' };
+  }
+
+  try {
+    const filePath = path.resolve(resourcesPath, document.file);
+    const relativePath = path.relative(path.resolve(resourcesPath), filePath);
+    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+      return { success: false, error: 'Invalid legal document path' };
+    }
+    return { success: true, content: fs.readFileSync(filePath, 'utf8') };
+  } catch {
+    return { success: false, error: 'Unable to read legal document' };
+  }
+}

app/electron/main.ts

@@ -42,6 +42,7 @@ import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import { setupCustomCAs, setupSystemCAs } from './certificates';
 import i18n from './i18next.config';
+import { loadLegalDocuments, readLegalDocument } from './legal-documents';
 import MCPClient from './mcp/MCPClient';
 import { filterUserOwnedPids } from './ownedProcesses';
 import {
@@ -192,6 +193,11 @@ const MAX_PORT_ATTEMPTS = Math.abs(Number(process.env.HEADLAMP_MAX_PORT_ATTEMPTS
 
 const useExternalServer = process.env.EXTERNAL_SERVER || false;
 const shouldCheckForUpdates = process.env.HEADLAMP_CHECK_FOR_UPDATES !== 'false';
+const appBuildManifestPath = path.join(
+  isDev ? path.resolve('./') : process.resourcesPath,
+  'app-build-manifest.json'
+);
+const legalDocuments = loadLegalDocuments(appBuildManifestPath);
 
 // make it global so that it doesn't get garbage collected
 let mainWindow: BrowserWindow | null;
@@ -811,11 +817,9 @@ async function startServer(flags: string[] = []): Promise<ChildProcessWithoutNul
     serverArgs = serverArgs.concat(['--kubeconfig', args.kubeconfig]);
   }
 
-  const manifestDir = isDev ? path.resolve('./') : process.resourcesPath;
-  const manifestFile = path.join(manifestDir, 'app-build-manifest.json');
   let buildManifest: Record<string, any> = {};
   try {
-    const manifestContent = await fsPromises.readFile(manifestFile, 'utf8');
+    const manifestContent = await fsPromises.readFile(appBuildManifestPath, 'utf8');
     buildManifest = JSON.parse(manifestContent);
   } catch (err) {
     // If the manifest doesn't exist or can't be read, fall back to empty object
@@ -1740,6 +1744,13 @@ function startElectron() {
       });
     });
 
+    ipcMain.handle('get-legal-documents', () =>
+      legalDocuments.map(({ id, title }) => ({ id, title }))
+    );
+    ipcMain.handle('get-legal-document', (_event, id: unknown) =>
+      readLegalDocument(process.resourcesPath, legalDocuments, id)
+    );
+
     ipcMain.on('pluginsLoaded', () => {
       loadFullMenu = true;
       console.info('Plugins are loaded. Loading full menu.');

app/electron/preload.ts

@@ -15,6 +15,7 @@
  */
 
 import { contextBridge, ipcRenderer } from 'electron';
+import type { LegalDocumentResult, LegalDocumentSummary } from './legal-documents';
 
 // Keeps the mapping between a caller-provided listener and the wrapped one we
 // actually register with ipcRenderer, so removeListener can still unsubscribe
@@ -117,4 +118,16 @@ contextBridge.exposeInMainWorld('desktopApi', {
   notifyClusterChange: (cluster: string | null) => {
     ipcRenderer.send('cluster-changed', cluster);
   },
+
+  /** @returns Legal documents declared by the packaged application manifest. */
+  getLegalDocuments: (): Promise<LegalDocumentSummary[]> =>
+    ipcRenderer.invoke('get-legal-documents'),
+  /**
+   * Reads a packaged legal document.
+   *
+   * @param id - Stable identifier returned by `getLegalDocuments`.
+   * @returns Document content or a stable failure result.
+   */
+  getLegalDocument: (id: string): Promise<LegalDocumentResult> =>
+    ipcRenderer.invoke('get-legal-document', id),
 });

app/package.json

@@ -162,6 +162,14 @@
       {
         "from": "./app-build-manifest.json",
         "to": "app-build-manifest.json"
+      },
+      {
+        "from": "../LICENSE",
+        "to": "LICENSE"
+      },
+      {
+        "from": "../NOTICE",
+        "to": "NOTICE"
       }
     ],
     "publish": {

frontend/src/components/App/LegalDocuments.tsx

@@ -0,0 +1,129 @@
+/*
+ * Copyright 2025 The Kubernetes Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import DialogActions from '@mui/material/DialogActions';
+import DialogContent from '@mui/material/DialogContent';
+import Typography from '@mui/material/Typography';
+import { useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Dialog } from '../common/Dialog';
+
+/** Public metadata for a legal document provided by the desktop host. */
+interface LegalDocument {
+  /** Stable identifier used to request the document content. */
+  id: string;
+  /** Human-readable document title. */
+  title: string;
+}
+
+/**
+ * Lists legal documents exposed by the desktop host and displays their content.
+ *
+ * @returns Legal document controls, or nothing when the host lacks the capability.
+ */
+export default function LegalDocuments() {
+  const { t } = useTranslation();
+  const [documents, setDocuments] = useState<LegalDocument[]>([]);
+  const [selectedDocument, setSelectedDocument] = useState<LegalDocument | null>(null);
+  const [content, setContent] = useState('');
+  const [error, setError] = useState('');
+  const getLegalDocuments = window.desktopApi?.getLegalDocuments;
+
+  useEffect(() => {
+    let active = true;
+    getLegalDocuments?.()
+      .then((items: LegalDocument[]) => {
+        if (active) {
+          setDocuments(items);
+        }
+      })
+      .catch(() => {
+        if (active) {
+          setError(t('translation|Unable to load legal documents.'));
+        }
+      });
+    return () => {
+      active = false;
+    };
+  }, [getLegalDocuments, t]);
+
+  /**
+   * Requests and presents one legal document.
+   *
+   * @param document - Document selected by the user.
+   * @returns A promise that settles after the host request is handled.
+   */
+  async function openDocument(document: LegalDocument): Promise<void> {
+    try {
+      const result = await window.desktopApi?.getLegalDocument?.(document.id);
+      if (result?.success) {
+        setSelectedDocument(document);
+        setContent(result.content ?? '');
+        setError('');
+      } else {
+        setError(result?.error ?? t('translation|Unable to load legal document.'));
+      }
+    } catch {
+      setError(t('translation|Unable to load legal document.'));
+    }
+  }
+
+  if (!getLegalDocuments) {
+    return null;
+  }
+
+  return (
+    <Box sx={{ p: 2 }}>
+      {documents.map(document => (
+        <Button key={document.id} onClick={() => openDocument(document)}>
+          {document.title}
+        </Button>
+      ))}
+      {error && (
+        <Typography role="alert" color="error">
+          {error}
+        </Typography>
+      )}
+      <Dialog
+        maxWidth="lg"
+        open={selectedDocument !== null}
+        onClose={() => setSelectedDocument(null)}
+        title={selectedDocument?.title ?? ''}
+      >
+        <DialogContent>
+          <Box
+            component="pre"
+            sx={{
+              whiteSpace: 'pre-wrap',
+              wordBreak: 'break-word',
+              fontFamily: 'monospace',
+              fontSize: '0.875rem',
+              maxHeight: '70vh',
+              overflow: 'auto',
+            }}
+          >
+            {content}
+          </Box>
+        </DialogContent>
+        <DialogActions>
+          <Button onClick={() => setSelectedDocument(null)}>{t('translation|Close')}</Button>
+        </DialogActions>
+      </Dialog>
+    </Box>
+  );
+}