web-os

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

| 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

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. Browser trying to register protocol handler on user interaction 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

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, `eval`ing 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:
```js
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.

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.

This site is open source. Improve this page.