web-os-spec

For web desktops

Version 1.0 approved
Prepared by Pablo Gracia
In collaboration with Supernova
11 February 2025

Table of Contents

• Revision History
• Introduction
  • 1.1 Purpose
  • 1.2 Document Conventions
  • 1.3 Intended Audience and Reading Suggestions
  • 1.4 Product Scope
  • 1.5 References
• Overall Description
  • 2.1 Product Perspective
  • 2.2 Product Functions
• External Interface Requirements
  • 3.1 User Interfaces
  • 3.2 Software Interfaces
• System Features
  • 4.1 File Method
  • 4.2 App Method
  • 4.3 Search Method
• Other Nonfunctional Requirements
  • 5.1 Performance Requirements
  • 5.2 Security Requirements
• Installation
• Usage Examples

Revision History

Name	Date	Reason For Changes	Version
Initial/v1.0.0	11 February 2025	Initial release	v1.0.0

1. Introduction

1.1 Purpose

The purpose of this document is to present a detailed description of the protocol handler web+os version 1.0.0. It will explain the purpose, usage, and methods of implementing the protocol handler.

1.2 Document Conventions

• Protocol Handler: Refers to the web+os protocol handler and its interface.
• Monospace Font: The protocol handler web+os is displayed in a monospace font to distinguish it from general Web OSes.
• Web OS: Refers to a desktop environment simulated in the browser, written with web programming languages. The term "Web Desktop" can also be used.
• WebOS: A TV operating system made by LG, unrelated to Web OSes.
• References: Links to MDN are provided in 1.5 References.
• Malware: Refers to malware affecting the Web OS, not the underlying operating system.

1.3 Intended Audience and Reading Suggestions

The document's intended audience is one of Web developers. If you do not have sufficient web development knowledge, we recommend you learn at MDN.
This document is written by members of the GitHub organization System41, which currently only contains one member. If you are looking for support with the protocol handler, please direct yourself towards the GitHub repository's Issues tab.

1.4 Product Scope

The software aims at enabling compatibility between websites and web OSes. One possible benefit of this is that a user can register their web OS of choice and a website can redirect them to install an application on their Web OS given that it is able to be installed.

1.5 References

• MDN - clear JavaScript documentation

Overall Description

2.1 Product Perspective

The protocol handler web+os is a new self-contained project. It is available on Chrome, Edge, Firefox, Opera, and Firefox for Android.

2.2 Product Functions

TODO: finish, release parser on npm

External Interface Requirements

3.1 User Interfaces

It is up to the Web OS developer to add a user interface when an action is performed with the protocol handler. It is recommended to not add any interface, and just continue by executing the action. It is also recommended to filter the action for XSS or malware that can negatively harm the Web OS. If undesireable results ensue, it is recommended to cancel the action and display a graphical interface explaining that the action could not be completed. This is explained in further detail in 5.2 Security Recommendations.

3.2 Software Interfaces

The protocol handler is registered on the Web OS by running the JavaScript function

window.navigator.registerProtocolHandler('web+os', WEB_OS_URL + '?protocol=%s', WEB_OS_NAME)

where WEB_OS_URL is the base URL of the Web OS and WEB_OS_NAME is the name of the Web OS. The name won't actually display in the prompt due to spoofing concerns (historically it displayed "Allow this site to handle [name] links?" while now it displays "Allow this site to handle web+os links?") but it is still required by most browsers. If the protocol handler is registered on a user interaction, the browser will display a window asking if the user would like to register it, as seen below. If not, the browser will most likely provide a small icon next to the favorites button. When clicked on, the browser will display a window asking if the user would like to register it. Because of the button's size, it is recommended to try to register the protocol handler only on user interaction

System Features

4.1 File method

web+os:file
The only element in this approach is file. This should be a path to a file, drive, or directory. This can include forward slashes and backslashes. If it is a directory or drive, the default file explorer/manager should open and show the directory or drive. If the file element is a file, the file's default opener should open it.

Implementation

The Web OS should handle the file element by parsing the path and determining whether it is a file, directory, or drive. The appropriate action should be taken based on the type of path provided.

Recommendations

• Ensure that the file path is valid and accessible within the Web OS.
• Provide appropriate error handling if the file, directory, or drive cannot be found or opened.
• Consider security implications and restrict access to sensitive files or directories.

4.2 Application method

web+os:app/options
The app element should execute an application. The app and options elements in the protocol may not contain a forward slash (/) or a backslash (\). These are the only limitations of this approach. Although we do recommend that you do not include spaces or capital letters, you may do so if you wish. The parser will not misinterpret the protocol if you do these things.

Implementation

The Web OS should handle the app and options elements by parsing the application name and options, and then executing the specified application with the provided options.

Recommendations

• Ensure that the application name and options are valid and recognized by the Web OS.
• Provide appropriate error handling if the application cannot be found or executed.
• Consider security implications and restrict execution of potentially harmful applications or options.

4.3 Search method

web+os:search/searchQuery The search method allows users to perform a search within the Web OS. The searchQuery element should be the query string that the user wants to search for. This method can be used to search for files, applications, or any other searchable content within the Web OS.

Implementation

The Web OS should handle the searchQuery by parsing the query string and performing the appropriate search action. The search results should be displayed in a user-friendly manner, such as in a list or grid format.

Recommendations

• The search method should be optimized for performance to ensure quick search results.
• The search results should be filtered to exclude any potentially harmful content.
• The search interface should be intuitive and easy to use for the end-user.

Other Nonfunctional Recommendations

5.1 Performance Recommendations

If the prompt is too large, the Web OS should

5.3 Security Recommendations

Your application should filter the content in the ?protocol query parameter, especially if it is generating HTML (or worse, evaling the prompt as JavaScript code)

Installation

To install the protocol handler within a web page, include the following JavaScript code in your Web OS initialization script:

window.navigator.registerProtocolHandler('web+os', WEB_OS_URL + '?protocol=%s', WEB_OS_NAME);

Replace WEB_OS_URL with the base URL of your Web OS and WEB_OS_NAME with the name of your Web OS.

Usage Examples

Example 1: Opening a file

To open a file using the protocol handler, use the following URL:

web+os:file/path/to/your/file.txt

This will open the specified file in the default file opener of the Web OS.

Example 2: Executing an application

To execute an application using the protocol handler, use the following URL:

web+os:app/yourAppName

This will execute the specified application in the Web OS.

Example 3: Performing a search

To perform a search using the protocol handler, use the following URL:

web+os:search/yourSearchQuery

This will perform the specified search in the Web OS.