@adecore/shell 0.17.0-beta.1 → 0.17.0-beta.2

package/LICENSE

@@ -1,13 +1,102 @@
-MIT License
+# Functional Source License, Version 1.1, MIT Future License
 
-Copyright (c) 2026 Bas Milius
+## Abbreviation
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 - present Bas Milius
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
 
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.

package/README.md

@@ -23,7 +23,7 @@ The package registers no IPC handler and listens to no app-wide Electron event.
 
 | Import | What it holds |
 |---|---|
-| `@adecore/shell` | For the main process: `createWindows`, `createWindowState`, `createUpdater`, `createTheme`, `menuTemplateOf`, `staticMenuTemplate`, `createMenuCommands`, `createPageKeys` and the web guards |
+| `@adecore/shell` | For the main process: `createWindows`, `createWindowState`, `createUpdater`, `createTheme`, `menuTemplateOf`, `staticMenuTemplate`, `createMenuCommands`, `createPageKeys`, `createAppScheme` and the web guards |
 | `@adecore/shell/bridge` | The shapes that cross IPC: `MenuSpec`, `MenuNode`, `MENU_ROLES`, `UpdateState`, `ThemeState` and `compareVersions`. It imports nothing from Electron, so a preload and the page read it too. |
 
 ## Documentation
@@ -36,8 +36,9 @@ The package registers no IPC handler and listens to no app-wide Electron event.
 | [Window state](https://adecore.dev/shell/window-state) | Each window opens where it was left |
 | [Theme](https://adecore.dev/shell/theme) | The page's theme on the window, its controls and Chromium |
 | [Web guards](https://adecore.dev/shell/web-guards) | Where the app's page may go, and who may speak for it |
+| [App scheme](https://adecore.dev/shell/app-scheme) | The app's page served from a scheme of its own, with the guards bound to it |
 | [Bridge](https://adecore.dev/shell/bridge) | The shapes that cross IPC |
 
 ## License
 
-MIT
+FSL-1.1-MIT, see [LICENSE](./LICENSE).

package/dist/app-scheme.d.ts

@@ -0,0 +1,34 @@
+import type { CustomScheme } from 'electron';
+import { type NavigationVerdict, type SenderFrame } from './web-guards.ts';
+export declare const APP_SCHEME_PRIVILEGES: NonNullable<CustomScheme['privileges']>;
+export interface SchemeFolder {
+    readonly root: string;
+    readonly routes?: boolean;
+    readonly headers?: Record<string, string> | ((file: string) => Record<string, string>);
+}
+export type SchemeResolver = (request: Request, url: URL) => Response | Promise<Response>;
+export interface AppSchemeOptions {
+    readonly scheme: string;
+    readonly host?: string;
+    readonly root: string;
+    readonly routes?: boolean;
+    readonly headers?: SchemeFolder['headers'];
+    readonly hosts?: Readonly<Record<string, SchemeFolder | SchemeResolver>>;
+    readonly pageUrl?: string;
+    readonly privileges?: CustomScheme['privileges'];
+    readonly read?: (file: string, request: Request) => Promise<Response>;
+}
+export interface AppScheme {
+    readonly scheme: string;
+    readonly url: string;
+    readonly origin: string;
+    readonly privileged: CustomScheme;
+    handle(request: Request): Promise<Response>;
+    serveFile(root: string, file: string, request: Request, headers?: Record<string, string>): Promise<Response>;
+    originOf(url: string): string | null;
+    isAppUrl(url: string): boolean;
+    navigation(url: string): NavigationVerdict;
+    isAppSender(isAppWindow: boolean, frame: SenderFrame | null): boolean;
+}
+export declare const segmentsOf: (pathname: string) => string[] | null;
+export declare function createAppScheme(options: AppSchemeOptions): AppScheme;

package/dist/app-scheme.js

@@ -0,0 +1,149 @@
+import { realpath, readFile, stat } from 'node:fs/promises';
+import { extname, isAbsolute, join, relative, resolve } from 'node:path';
+import { appWindowNavigation, isAppSender, originOf } from './web-guards.js';
+/*
+ * Standard and secure give the page a real origin and a secure context (WebCrypto), fetch and CORS let it
+ * load from the scheme and talk to a backend, streaming serves big files, the code cache keeps compiled
+ * scripts between starts, and a service worker needs its own privilege.
+ */
+export const APP_SCHEME_PRIVILEGES = {
+    standard: true,
+    secure: true,
+    supportFetchAPI: true,
+    corsEnabled: true,
+    stream: true,
+    codeCache: true,
+    allowServiceWorkers: true
+};
+const CONTENT_TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json',
+    '.map': 'application/json',
+    '.webmanifest': 'application/manifest+json',
+    // A WebAssembly module compiles while it streams only under its own type.
+    '.wasm': 'application/wasm',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.ico': 'image/x-icon',
+    '.woff2': 'font/woff2',
+    '.woff': 'font/woff',
+    '.ttf': 'font/ttf',
+    '.otf': 'font/otf',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.ogg': 'audio/ogg',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.txt': 'text/plain; charset=utf-8'
+};
+const notFound = () => new Response('Not found', { status: 404 });
+const readWhole = async (file) => new Response(new Uint8Array(await readFile(file)));
+/* The segments of a path as the URL carries them, decoded, or null when one could climb out or means nothing on its own. */
+export const segmentsOf = (pathname) => {
+    const path = pathname.replace(/^\/+/, '');
+    if (path === '') {
+        return [];
+    }
+    const segments = [];
+    for (const raw of path.split('/')) {
+        let segment;
+        try {
+            segment = decodeURIComponent(raw);
+        }
+        catch {
+            return null;
+        }
+        if (segment === '' || segment === '.' || segment === '..' || /[/\\\0]/.test(segment)) {
+            return null;
+        }
+        segments.push(segment);
+    }
+    return segments;
+};
+const isInside = (root, path) => {
+    const between = relative(root, path);
+    return between !== '' && !between.startsWith('..') && !isAbsolute(between);
+};
+/*
+ * Registers nothing by itself: the app hands `privileged` to `protocol.registerSchemesAsPrivileged`
+ * before it is ready and `handle` to `protocol.handle`, on the sessions it picks. Every file it serves
+ * lies inside the folder of its host, also after following a symlink.
+ */
+export function createAppScheme(options) {
+    const scheme = options.scheme;
+    const pageHost = (options.host ?? 'app').toLowerCase();
+    const schemes = [scheme];
+    const own = `${scheme}://${pageHost}`;
+    const url = options.pageUrl ?? `${own}/`;
+    const origin = originOf(url, schemes) ?? own;
+    const read = options.read ?? readWhole;
+    const hosts = new Map(Object.entries(options.hosts ?? {}).map(([name, host]) => [name.toLowerCase(), host]));
+    hosts.set(pageHost, { root: options.root, routes: options.routes ?? true, headers: options.headers });
+    const serveFile = async (root, file, request, headers = {}) => {
+        let found;
+        try {
+            const [realRoot, realFile] = await Promise.all([realpath(resolve(root)), realpath(resolve(file))]);
+            if (!isInside(realRoot, realFile) || !(await stat(realFile)).isFile()) {
+                return notFound();
+            }
+            found = realFile;
+        }
+        catch {
+            return notFound();
+        }
+        const response = await read(found, request);
+        const merged = new Headers(response.headers);
+        const type = CONTENT_TYPES[extname(found).toLowerCase()];
+        if (type !== undefined) {
+            merged.set('content-type', type);
+        }
+        for (const [name, value] of Object.entries(headers)) {
+            merged.set(name, value);
+        }
+        return new Response(response.body, { status: response.status, statusText: response.statusText, headers: merged });
+    };
+    const serveFolder = (folder, request, address) => {
+        const segments = segmentsOf(address.pathname);
+        if (segments === null) {
+            return notFound();
+        }
+        // A missing chunk with an extension stays a 404, so a stale one fails as a load error rather than as the page.
+        const page = segments.length === 0 || (folder.routes === true && extname(segments.at(-1)) === '');
+        const file = page ? join(folder.root, 'index.html') : join(folder.root, ...segments);
+        const headers = typeof folder.headers === 'function' ? folder.headers(file) : folder.headers;
+        return serveFile(folder.root, file, request, headers);
+    };
+    return {
+        scheme,
+        url,
+        origin,
+        privileged: { scheme, privileges: options.privileges ?? APP_SCHEME_PRIVILEGES },
+        handle: async (request) => {
+            let address;
+            try {
+                address = new URL(request.url);
+            }
+            catch {
+                return notFound();
+            }
+            const host = address.protocol === `${scheme}:` ? hosts.get(address.host.toLowerCase()) : undefined;
+            if (host === undefined) {
+                return notFound();
+            }
+            return typeof host === 'function' ? host(request, address) : serveFolder(host, request, address);
+        },
+        serveFile,
+        originOf: (address) => originOf(address, schemes),
+        isAppUrl: (address) => originOf(address, schemes) === origin,
+        navigation: (address) => appWindowNavigation(address, origin, schemes),
+        isAppSender: (isAppWindow, frame) => isAppSender(isAppWindow, frame, origin, schemes)
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { APP_SCHEME_PRIVILEGES, createAppScheme, segmentsOf } from './app-scheme.ts';
+export type { AppScheme, AppSchemeOptions, SchemeFolder, SchemeResolver } from './app-scheme.ts';
 export { createMenuCommands, devToolsAccelerator, menuTemplateOf, staticMenuTemplate } from './menu.ts';
 export type { MenuCommandOptions, MenuTemplateOptions, MenuWindow, StaticMenuOptions } from './menu.ts';
 export { createPageKeys, PAGE_KEY_MS } from './page-keys.ts';

package/dist/index.js

@@ -1,3 +1,4 @@
+export { APP_SCHEME_PRIVILEGES, createAppScheme, segmentsOf } from './app-scheme.js';
 export { createMenuCommands, devToolsAccelerator, menuTemplateOf, staticMenuTemplate } from './menu.js';
 export { createPageKeys, PAGE_KEY_MS } from './page-keys.js';
 export { createUpdater, describeUpdateError, UPDATE_INTERVAL_MS } from './updater.js';

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@adecore/shell",
-  "version": "0.17.0-beta.1",
+  "version": "0.17.0-beta.2",
   "description": "The main process of an Electron app: its menu, its updater and the guards around its page.",
-  "license": "MIT",
+  "license": "FSL-1.1-MIT",
   "author": "Bas Milius",
   "repository": {
     "type": "git",

package/src/app-scheme.ts

@@ -0,0 +1,204 @@
+import { realpath, readFile, stat } from 'node:fs/promises';
+import { extname, isAbsolute, join, relative, resolve } from 'node:path';
+import type { CustomScheme } from 'electron';
+import { appWindowNavigation, isAppSender, originOf, type NavigationVerdict, type SenderFrame } from './web-guards.ts';
+
+/*
+ * Standard and secure give the page a real origin and a secure context (WebCrypto), fetch and CORS let it
+ * load from the scheme and talk to a backend, streaming serves big files, the code cache keeps compiled
+ * scripts between starts, and a service worker needs its own privilege.
+ */
+export const APP_SCHEME_PRIVILEGES: NonNullable<CustomScheme['privileges']> = {
+    standard: true,
+    secure: true,
+    supportFetchAPI: true,
+    corsEnabled: true,
+    stream: true,
+    codeCache: true,
+    allowServiceWorkers: true
+};
+
+const CONTENT_TYPES: Readonly<Record<string, string>> = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json',
+    '.map': 'application/json',
+    '.webmanifest': 'application/manifest+json',
+    // A WebAssembly module compiles while it streams only under its own type.
+    '.wasm': 'application/wasm',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.ico': 'image/x-icon',
+    '.woff2': 'font/woff2',
+    '.woff': 'font/woff',
+    '.ttf': 'font/ttf',
+    '.otf': 'font/otf',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.ogg': 'audio/ogg',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.txt': 'text/plain; charset=utf-8'
+};
+
+export interface SchemeFolder {
+    readonly root: string;
+    /* A page that routes itself: an address without an extension gets its `index.html`. Otherwise only `/` does. */
+    readonly routes?: boolean;
+    /* On every response of the folder, such as a `Content-Security-Policy`, or per file. */
+    readonly headers?: Record<string, string> | ((file: string) => Record<string, string>);
+}
+
+/* A host that answers a request itself, such as files it finds by an id; `serveFile` serves what it found. */
+export type SchemeResolver = (request: Request, url: URL) => Response | Promise<Response>;
+
+export interface AppSchemeOptions {
+    /* Without the colon, such as `app`. */
+    readonly scheme: string;
+    /* The host of the page; `app` without one. */
+    readonly host?: string;
+    /* The built page. It routes itself unless `routes` is false. */
+    readonly root: string;
+    readonly routes?: boolean;
+    readonly headers?: SchemeFolder['headers'];
+    /* Other hosts on the same scheme, by name: a folder of their own or a resolver. */
+    readonly hosts?: Readonly<Record<string, SchemeFolder | SchemeResolver>>;
+    /* The URL the window loads instead, such as a dev server; the guards then take its origin for the app's. */
+    readonly pageUrl?: string;
+    readonly privileges?: CustomScheme['privileges'];
+    /* Answers with a file the scheme found. Reads it whole without one; `net.fetch` of its `file:` URL streams it. */
+    readonly read?: (file: string, request: Request) => Promise<Response>;
+}
+
+export interface AppScheme {
+    readonly scheme: string;
+    /* What the window loads: `pageUrl`, or the root of the page's host. */
+    readonly url: string;
+    /* The origin the guards take for the app's. */
+    readonly origin: string;
+    /* For `protocol.registerSchemesAsPrivileged`, before the app is ready. */
+    readonly privileged: CustomScheme;
+    /* For `protocol.handle`: the file a request names, or a 404. */
+    handle(request: Request): Promise<Response>;
+    /* Serves `file` when it lies inside `root`, for a resolver of a host. */
+    serveFile(root: string, file: string, request: Request, headers?: Record<string, string>): Promise<Response>;
+    originOf(url: string): string | null;
+    isAppUrl(url: string): boolean;
+    navigation(url: string): NavigationVerdict;
+    isAppSender(isAppWindow: boolean, frame: SenderFrame | null): boolean;
+}
+
+const notFound = (): Response => new Response('Not found', { status: 404 });
+
+const readWhole = async (file: string): Promise<Response> => new Response(new Uint8Array(await readFile(file)));
+
+/* The segments of a path as the URL carries them, decoded, or null when one could climb out or means nothing on its own. */
+export const segmentsOf = (pathname: string): string[] | null => {
+    const path = pathname.replace(/^\/+/, '');
+    if (path === '') {
+        return [];
+    }
+    const segments: string[] = [];
+    for (const raw of path.split('/')) {
+        let segment: string;
+        try {
+            segment = decodeURIComponent(raw);
+        } catch {
+            return null;
+        }
+        if (segment === '' || segment === '.' || segment === '..' || /[/\\\0]/.test(segment)) {
+            return null;
+        }
+        segments.push(segment);
+    }
+    return segments;
+};
+
+const isInside = (root: string, path: string): boolean => {
+    const between = relative(root, path);
+    return between !== '' && !between.startsWith('..') && !isAbsolute(between);
+};
+
+/*
+ * Registers nothing by itself: the app hands `privileged` to `protocol.registerSchemesAsPrivileged`
+ * before it is ready and `handle` to `protocol.handle`, on the sessions it picks. Every file it serves
+ * lies inside the folder of its host, also after following a symlink.
+ */
+export function createAppScheme(options: AppSchemeOptions): AppScheme {
+    const scheme = options.scheme;
+    const pageHost = (options.host ?? 'app').toLowerCase();
+    const schemes = [scheme];
+    const own = `${scheme}://${pageHost}`;
+    const url = options.pageUrl ?? `${own}/`;
+    const origin = originOf(url, schemes) ?? own;
+    const read = options.read ?? readWhole;
+    const hosts = new Map<string, SchemeFolder | SchemeResolver>(Object.entries(options.hosts ?? {}).map(([name, host]) => [name.toLowerCase(), host]));
+    hosts.set(pageHost, { root: options.root, routes: options.routes ?? true, headers: options.headers });
+
+    const serveFile = async (root: string, file: string, request: Request, headers: Record<string, string> = {}): Promise<Response> => {
+        let found: string;
+        try {
+            const [realRoot, realFile] = await Promise.all([realpath(resolve(root)), realpath(resolve(file))]);
+            if (!isInside(realRoot, realFile) || !(await stat(realFile)).isFile()) {
+                return notFound();
+            }
+            found = realFile;
+        } catch {
+            return notFound();
+        }
+        const response = await read(found, request);
+        const merged = new Headers(response.headers);
+        const type = CONTENT_TYPES[extname(found).toLowerCase()];
+        if (type !== undefined) {
+            merged.set('content-type', type);
+        }
+        for (const [name, value] of Object.entries(headers)) {
+            merged.set(name, value);
+        }
+        return new Response(response.body, { status: response.status, statusText: response.statusText, headers: merged });
+    };
+
+    const serveFolder = (folder: SchemeFolder, request: Request, address: URL): Promise<Response> | Response => {
+        const segments = segmentsOf(address.pathname);
+        if (segments === null) {
+            return notFound();
+        }
+        // A missing chunk with an extension stays a 404, so a stale one fails as a load error rather than as the page.
+        const page = segments.length === 0 || (folder.routes === true && extname(segments.at(-1)!) === '');
+        const file = page ? join(folder.root, 'index.html') : join(folder.root, ...segments);
+        const headers = typeof folder.headers === 'function' ? folder.headers(file) : folder.headers;
+        return serveFile(folder.root, file, request, headers);
+    };
+
+    return {
+        scheme,
+        url,
+        origin,
+        privileged: { scheme, privileges: options.privileges ?? APP_SCHEME_PRIVILEGES },
+        handle: async (request) => {
+            let address: URL;
+            try {
+                address = new URL(request.url);
+            } catch {
+                return notFound();
+            }
+            const host = address.protocol === `${scheme}:` ? hosts.get(address.host.toLowerCase()) : undefined;
+            if (host === undefined) {
+                return notFound();
+            }
+            return typeof host === 'function' ? host(request, address) : serveFolder(host, request, address);
+        },
+        serveFile,
+        originOf: (address) => originOf(address, schemes),
+        isAppUrl: (address) => originOf(address, schemes) === origin,
+        navigation: (address) => appWindowNavigation(address, origin, schemes),
+        isAppSender: (isAppWindow, frame) => isAppSender(isAppWindow, frame, origin, schemes)
+    };
+}

package/src/index.ts

@@ -1,3 +1,5 @@
+export { APP_SCHEME_PRIVILEGES, createAppScheme, segmentsOf } from './app-scheme.ts';
+export type { AppScheme, AppSchemeOptions, SchemeFolder, SchemeResolver } from './app-scheme.ts';
 export { createMenuCommands, devToolsAccelerator, menuTemplateOf, staticMenuTemplate } from './menu.ts';
 export type { MenuCommandOptions, MenuTemplateOptions, MenuWindow, StaticMenuOptions } from './menu.ts';
 export { createPageKeys, PAGE_KEY_MS } from './page-keys.ts';